Astronomer Deployment API

openapi: 3.0.3
info:
  contact: {}
  description: Astro Platform API
  title: Astro Platform AgentToken Deployment API
  version: v1.0
servers:
- url: https://api.astronomer.io/v1
security:
- JWT: []
tags:
- description: The `deployment` object represents an Astro Deployment, which is a hosted Airflow environment that is powered by all core Airflow components, including schedulers and workers. Make requests to the `deployment` object to create, update, or delete a Deployment or its computational resources. See [Deployment settings](https://astronomer.io/docs/astro/deployment-settings).
  name: Deployment
paths:
  /organizations/{organizationId}/deployments:
    get:
      description: List Deployments in an Organization.
      operationId: ListDeployments
      parameters:
      - description: The ID of the Organization to list Deployments for.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: A list of IDs for Deployments to show. The API returns details only for the specified Deployments.
        in: query
        name: deploymentIds
        schema:
          items:
            type: string
          type: array
      - description: A list of names for Deployments to filter by. The API returns details only for the specified Deployments.
        in: query
        name: names
        schema:
          items:
            type: string
          type: array
      - description: A list of IDs for Workspaces to filter on. The API returns details for all Deployments belonging only to the specified Workspaces.
        in: query
        name: workspaceIds
        schema:
          items:
            type: string
          type: array
      - 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
          minimum: 0
          type: integer
      - description: A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `<fieldName>:asc` or `<fieldName>:desc`.
        in: query
        name: sorts
        schema:
          items:
            enum:
            - name:asc
            - name:desc
            - createdAt:asc
            - createdAt:desc
            - updatedAt:asc
            - updatedAt:desc
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentsPaginated'
          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: List Deployments
      tags:
      - Deployment
      x-permission:
      - action: organization.deployments.get
    post:
      description: Create a Deployment in the Organization. An Astro Deployment is an Airflow environment that is powered by all core Airflow components.
      operationId: CreateDeployment
      parameters:
      - description: The ID of the Organization in which to create the Deployment.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentRequest'
        description: The request body for creating a Deployment.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
          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: Create a Deployment
      tags:
      - Deployment
      x-permission:
      - action: workspace.deployments.create
  /organizations/{organizationId}/deployments/{deploymentId}:
    delete:
      description: Delete a Deployment from an Organization.
      operationId: DeleteDeployment
      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
      responses:
        '204':
          description: ''
        '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: Delete a Deployment
      tags:
      - Deployment
      x-permission:
      - action: deployment.delete
    get:
      description: Retrieve details about a Deployment.
      operationId: GetDeployment
      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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
          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 Deployment
      tags:
      - Deployment
      x-permission:
      - action: deployment.get
    post:
      description: Update a Deployment in the Organization.
      operationId: UpdateDeployment
      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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDeploymentRequest'
        description: The request body for updating a Deployment.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
          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 Deployment
      tags:
      - Deployment
      x-permission:
      - action: deployment.update
  /organizations/{organizationId}/deployments/{deploymentId}/hibernation-override:
    delete:
      operationId: DeleteDeploymentHibernationOverride
      parameters:
      - description: The Organization ID
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The Deployment ID
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      responses:
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: a common error response
        5XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: a common error response
        '204':
          description: No Content
      security:
      - JWT: []
      summary: Delete a hibernation override for a deployment
      tags:
      - Deployment
      x-permission:
      - action: deployment.update
    post:
      operationId: UpdateDeploymentHibernationOverride
      parameters:
      - description: The Organization ID
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The Deployment ID
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OverrideDeploymentHibernationBody'
        required: true
      responses:
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: a common error response
        5XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: a common error response
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentHibernationOverride'
          description: OK
      security:
      - JWT: []
      summary: Configure a hibernation override for a deployment
      tags:
      - Deployment
      x-permission:
      - action: deployment.update
  /organizations/{organizationId}/deployments/{deploymentId}/logs:
    get:
      description: Get logs for an Astro Deployment. You must specify at least one log source.
      operationId: GetDeploymentLogs
      parameters:
      - description: The ID of the Organization to which the Deployment belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the Deployment to get logs for.
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      - description: Log sources to retrieve.
        in: query
        name: sources
        required: true
        schema:
          items:
            enum:
            - scheduler
            - triggerer
            - worker
            - webserver
            - dag-processor
            - apiserver
            type: string
          type: array
      - description: Maximum number of log entries per page.
        in: query
        name: limit
        schema:
          default: 500
          minimum: 1
          type: integer
      - description: Offset for pagination.
        in: query
        name: offset
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: Range of the log search in seconds.
        in: query
        name: range
        schema:
          default: 3600
          minimum: 60
          type: integer
      - description: Maximum total number of results across all pages.
        in: query
        name: maxNumResults
        schema:
          default: 10000
          minimum: 1
          type: integer
      - description: Search ID for paginated results.
        in: query
        name: searchId
        schema:
          type: string
      - description: Text to filter logs by.
        in: query
        name: searchText
        schema:
          type: string
      - description: Start of time range (RFC3339).  Must  be  used  with  endDate.
        in: query
        name: startDate
        schema:
          format: date-time
          type: string
      - description: End of time range (RFC3339).    Must  be  used  with  startDate.
        in: query
        name: endDate
        schema:
          format: date-time
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentLog'
          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: Get Deployment logs
      tags:
      - Deployment
      x-permission:
      - action: deployment.logs.get
components:
  schemas:
    HybridWorkerQueueRequest:
      properties:
        id:
          description: The worker queue's ID. If not provided, a new worker queue will be created.
          example: clmha1mzc000b08mi96n182au
          type: string
        isDefault:
          description: Whether the worker queue is the default worker queue on the Deployment.
          example: true
          type: boolean
        maxWorkerCount:
          description: The maximum number of workers that can run at once.
          minimum: 1
          type: integer
        minWorkerCount:
          description: The minimum number of workers running at once.
          minimum: 0
          type: integer
        name:
          description: The worker queue's name.
          example: My worker queue
          maxLength: 63
          type: string
        nodePoolId:
          description: The node pool ID associated with the worker queue.
          type: string
        workerConcurrency:
          description: The maximum number of concurrent tasks that a worker Pod can run at a time.
          minimum: 1
          type: integer
      required:
      - isDefault
      - maxWorkerCount
      - minWorkerCount
      - name
      - nodePoolId
      - workerConcurrency
      type: object
    DeploymentLogEntry:
      properties:
        raw:
          description: The raw log entry content.
          type: string
        source:
          description: The log entry source.
          enum:
          - scheduler
          - webserver
          - triggerer
          - worker
          - dag-processor
          - apiserver
          type: string
        timestamp:
          description: The log entry's timestamp.
          type: number
      required:
      - raw
      - source
      - timestamp
      type: object
    UpdateWorkerQueueRequest:
      properties:
        astroMachine:
          description: The Astro machine for each worker in the queue. Required for Astro Hosted deployments.
          enum:
          - A5
          - A10
          - A20
          - A40
          - A60
          - A120
          - A160
          type: string
        id:
          description: The worker queue's ID. If not provided, a new worker queue will be created.
          example: clmha1mzc000b08mi96n182au
          type: string
        isDefault:
          description: Whether the worker queue is the default worker queue on the Deployment.
          example: true
          type: boolean
        maxWorkerCount:
          description: The maximum number of workers that can run at once.
          minimum: 1
          type: integer
        minWorkerCount:
          description: The minimum number of workers running at once.
          minimum: 0
          type: integer
        name:
          description: The worker queue's name.
          example: My worker queue
          maxLength: 63
          type: string
        nodePoolId:
          description: The node pool ID associated with the worker queue. Required for Hybrid deployments.
          type: string
        podEphemeralStorage:
          description: The ephemeral storage limit for each worker Pod. Must be a valid Kubernetes resource string, e.g. `10Gi`.
          type: string
        workerConcurrency:
          description: The maximum number of concurrent tasks that a worker Pod can run at a time.
          minimum: 1
          type: integer
      required:
      - isDefault
      - maxWorkerCount
      - minWorkerCount
      - name
      - workerConcurrency
      type: object
    DeploymentScalingSpecRequest:
      properties:
        hibernationSpec:
          $ref: '#/components/schemas/DeploymentHibernationSpecRequest'
      type: object
    CreateStandardDeploymentRequest:
      properties:
        astroRuntimeVersion:
          description: Deployment's Astro Runtime version.
          example: 9.1.0
          type: string
        cloudProvider:
          description: Cloud provider for STANDARD deployments on Astronomer shared infrastructure. One of AWS, AZURE, GCP. Must be provided together with region. If clusterId is also provided, clusterId takes precedence and this field is ignored.
          enum:
          - AWS
          - AZURE
          - GCP
          example: GCP
          type: string
        clusterId:
          description: The target cluster ID. Use for DEDICATED (Astronomer-hosted) or HYBRID (Bring-Your-Own-Cloud) deployments. If provided alongside cloudProvider and region, clusterId takes precedence and the other two are ignored. When all three are omitted, infrastructure is resolved from workspace defaults or auto-selected when the organization has exactly one cluster.
          example: clmh93n2n000008ms3tv79voh
          type: string
        contactEmails:
          description: A list of contact emails for the Deployment.
          example:
          - user1@company.com
          items:
            type: string
          type: array
        defaultTaskPodCpu:
          description: The default CPU resource usage for a worker Pod when running the Kubernetes executor or KubernetesPodOperator. Units are in number of CPU cores. Required if Remote Execution is disabled.
          example: '0.5'
          type: string
        defaultTaskPodMemory:
          description: The default memory resource usage for a worker Pod when running the Kubernetes executor or KubernetesPodOperator. Units are in `Gi` and must be explicitly included. This value must always be twice the value of `DefaultTaskPodCpu`. Required if Remote Execution is disabled.
          example: 1Gi
          type: string
        description:
          description: The Deployment's description.
          example: My deployment description
          maxLength: 1000
          type: string
        drWorkloadIdentity:
          description: The Deployment's DR workload identity.
          example: arn:aws:iam::123456789:role/AirflowS3Logs-clmk2qqia000008mhff3ndjr0
          type: string
        environmentVariables:
          description: List of environment variables to add to the Deployment.
          items:
            $ref: '#/components/schemas/DeploymentEnvironmentVariableRequest'
          type: array
        executor:
          description: The Deployment's executor type.
          enum:
          - CELERY
          - KUBERNETES
          - ASTRO
          example: CELERY
          type: string
        isCicdEnforced:
          description: Whether the Deployment requires that all deploys are made through CI/CD.
          example: true
          type: boolean
        isDagDeployEnabled:
          description: Whether the Deployment has DAG deploys enabled.
          example: true
          type: boolean
        isDevelopmentMode:
          description: If true, deployment will be able to use development-only features, such as hibernation, but will not have guaranteed uptime SLAs
          type: boolean
        isHighAvailability:
          description: Whether the Deployment is configured for high availability. If `true`, multiple scheduler pods will be online.
          example: true
          type: boolean
        name:
          description: The Deployment's name.
          example: My deployment
          maxLength: 500
          type: string
        region:
          description: Region for STANDARD deployments on Astronomer shared infrastructure. Must be provided together with cloudProvider. If clusterId is also provided, clusterId takes precedence and this field is ignored.
          example: us-east4
          type: string
        remoteExecution:
          $ref: '#/components/schemas/DeploymentRemoteExecutionRequest'
        resourceQuotaCpu:
          description: The CPU quota for worker Pods when running the Kubernetes executor or KubernetesPodOperator. If current CPU usage across all workers exceeds the quota, no new worker Pods can be scheduled. Units are in number of CPU cores. Required if Remote Execution is disabled.
          example: '160'
          type: string
        resourceQuotaMemory:
          description: The memory quota for worker Pods when running the Kubernetes executor or KubernetesPodOperator. If current memory usage across all workers exceeds the quota, no new worker Pods can be scheduled. Units are in `Gi` and must be explicitly included. This value must always be twice the value of `ResourceQuotaCpu`. Required if Remote Execution is disabled.
          example: 320Gi
          type: string
        scalingSpec:
          $ref: '#/components/schemas/DeploymentScalingSpecRequest'
        schedulerSize:
          description: The size of the scheduler Pod.
          enum:
          - SMALL
          - MEDIUM
          - LARGE
          - EXTRA_LARGE
          example: MEDIUM
          type: string
        type:
          description: The type of the Deployment.
          enum:
          - DEDICATED
          - HYBRID
          - STANDARD
          example: DEDICATED
          type: string
        workerQueues:
          description: A list of the Deployment's worker queues. Applies only when `Executor` is `CELERY` or if Remote Execution is disabled and executor is `ASTRO`. All these Deployments need at least 1 worker queue called `default`.
          items:
            $ref: '#/components/schemas/WorkerQueueRequest'
          minItems: 1
          type: array
        workloadIdentity:
          description: The Deployment's workload identity.
          example: arn:aws:iam::123456789:role/AirflowS3Logs-clmk2qqia000008mhff3ndjr0
          type: string
        workspaceId:
          description: The ID of the Workspace to which the Deployment belongs.
          example: clmh8ol3x000008jo656y4285
          type: string
      required:
      - name
      - workspaceId
      type: object
    DeploymentEnvironmentVariableRequest:
      properties:
        isSecret:
          description: Whether the environment variable is a secret.
          example: false
          type: boolean
        key:
          description: The environment variable key, used to call the value in code.
          example: my-var
          type: string
        value:
          description: The environment variable value.
          example: my-var-value
          type: string
      required:
      - isSecret
      - key
      type: object
    CreateDeploymentRequest:
      discriminator:
        mapping:
          DEDICATED: '#/components/schemas/CreateDedicatedDeploymentRequest'
          HYBRID: '#/components/schemas/CreateHybridDeploymentRequest'
          STANDARD: '#/components/schemas/CreateStandardDeploymentRequest'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/CreateDedicatedDeploymentRequest'
      - $ref: '#/components/schemas/CreateHybridDeploymentRequest'
      - $ref: '#/components/schemas/CreateStandardDeploymentRequest'
      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
    DeploymentHibernationOverride:
      properties:
        isActive:
          description: Whether the override is currently active or not
          type: boolean
        isHibernating:
          description: Whether to go into hibernation or not via the override rule
          type: boolean
        overrideUntil:
          description: Timestamp till the override on the hibernation schedule is in effect
          format: date-time
          type: string
      type: object
    UpdateDedicatedDeploymentRequest:
      properties:
        contactEmails:
          description: A list of contact emails for the Deployment.
          example:
          - user1@company.com
          items:
            type: string
          type: array
        defaultTaskPodCpu:
          description: The default CPU resource usage for a worker Pod when running the Kubernetes executor or KubernetesPodOperator. Units are in number of CPU cores. Required if Remote Execution is disabled.
          example: '0.5'
          type: string
        defaultTaskPodMemory:
          description: The default memory resource usage for a worker Pod when running the Kubernetes executor or KubernetesPodOperator. Units are in `Gi` and must be explicitly included. This value must always be twice the value of `DefaultTaskPodCpu`. Required if Remote Execution is disabled.
          example: 1Gi
          type: string
        description:
          description: The Deployment's description.
          example: My deployment description
          maxLength: 1000
          type: string
        drWorkloadIdentity:
          description: The Deployment's DR workload identity.
          example: arn:aws:iam::123456789:role/AirflowS3Logs-clmk2qqia000008mhff3ndjr0
          type: string
        environmentVariables:
          description: List of environment variables to add to the Deployment.
          items:
            $ref: '#/components/schemas/DeploymentEnvironmentVariableRequest'
          type: array
        executor:
          description: The Deployment's executor type.
          enum:
          - CELERY
          - KUBERNETES
          - ASTRO
          example: CELERY
          type: string
        isCicdEnforced:
          description: Whether the Deployment requires that all deploys are made through CI/CD.
          example: true
          type: boolean
        isDagDeployEnabled:
          description: Whether the Deployment has DAG deploys enabled.
          example: true
          type: boolean
        isDevelopmentMode:
          description: Whether the Deployment is for development only. If `false`, the Deployment can be considered production for the purposes of support case priority, but development-only features such as hibernation will not be available. You can't update this value to `true` for existing non-development Deployments.
          type: boolean
        isHighAvailability:
          description: Whether the Deployment is configured for high availability. If `true`, multiple scheduler pods will be online.
          example: true
          type: boolean
        name:
          description: The Deployment's name.
          example: My deployment
          maxLength: 500
          type: string
        remoteExecution:
          $ref: '#/components/schemas/DeploymentRemoteExecutionRequest'
        resourceQuotaCpu:
          description: The CPU quota for worker Pods when running the Kubernetes executor or KubernetesPodOperator. If current CPU usage across all workers exceeds the quota, no new worker Pods can be scheduled. Units are in number of CPU cores. Required if Remote Execution is disabled.
          example: '160'
          type: string
        resourceQuotaMemory:
          description: The memory quota for worker Pods when running the Kubernetes executor or KubernetesPodOperator. If current memory usage across all workers exceeds the quota, no new worker Pods can be scheduled. Units are in `Gi` and must be explicitly included. This value must always be twice the value of `ResourceQuotaCpu`. Required if Remote Execution is disabled.
          example: 320Gi
          type: string
        scalingSpec:
          $ref: '#/components/schemas/DeploymentScalingSpecRequest'
        schedulerSize:
          description: The size of the scheduler Pod.
          enum:
          - SMALL
          - MEDIUM
          - LARGE
          - EXTRA_LARGE
          example: MEDIUM
          type: string
        type:
          description: The type of the Deployment.
          enum:
    

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