openapi: "3.1.0"
info:
  version: "{{ spec_version }}"
  title: Hail Services
  # termsOfService: TBC
  contact:
    name: Contact our support
    email: hail-team@broadinstitute.org
    url: https://www.hail.is/gethelp.html
  license:
    name: MIT Licence
    url: https://github.com/hail-is/hail/blob/main/LICENSE
  x-logo:
    url: 'https://hail.is/static/hail-logo-cropped-sm-opt.png'
    altText: Hail logo
  description: >
    Hail batch is a service for running arbitrary jobs at scale.
tags:
  - name: Public Server Information
    description: "Operations for retrieving basic public information from the service."
  - name: Authenticated Server Information
    description: "Operations for retrieving information that require authentication."
  - name: Batches API v1Alpha
    description: "v1alpha batches API"
  - name: Batches API v2Alpha
    description: "v2alpha batches API"
  - name: Billing Projects
    description: "Operations for billing projects."
  - name: UI Support
servers:
  - url: "{{ base_url }}"
    description: "Current Batch service."
paths:
  '/api/v1alpha/version':
    get:
      summary: Get version
      description: Get the current version of the batch service
      tags: [System]
      responses:
        '200':
          description: Version retrieved successfully
          content:
            text/plain:
              schema:
                type: string
  '/healthcheck':
    get:
      summary: "Healthcheck"
      description: "Check the health of the API."
      operationId: healthcheck
      tags:
        - Public Server Information
      responses:
        '200':
          description: "Successfully checked the health of the API."
  '/api/v1alpha/cloud':
    get:
      summary: Get cloud provider
      description: Get the current cloud provider (gcp or azure)
      tags: [System]
      responses:
        '200':
          description: Cloud provider retrieved successfully
          content:
            text/plain:
              schema:
                type: string
                enum: [gcp, azure]
  '/api/v1alpha/supported_regions':
    get:
      summary: "Supported Regions"
      description: "Get the list of supported regions."
      operationId: getSupportedRegions
      tags:
        - Authenticated Server Information
      responses:
        '200':
          description: "Successfully retrieved the regions list."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedRegionsResponse'
  '/api/v1alpha/batches':
    get:
      summary: "List batches"
      description: "List batches."
      operationId: getBatchesv1alpha
      tags:
        - Batches API v1Alpha
      responses:
        '200':
          description: "Successfully retrieved the batches."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchListResponse'
  '/api/v1alpha/batches/create':
    post:
      summary: "Create a batch"
      description: "Create a batch."
      operationId: createBatchv1alpha
      tags:
        - Batches API v1Alpha
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBatchRequest'
      responses:
        '200':
          description: "Successfully created the batch."
          content:
            application/json:
              schema:
                type: object
  '/api/v1alpha/batches/create-fast':
    post:
      summary: "Create a batch fast"
      description: "Create a batch fast."
      operationId: createBatchFastv1alpha
      tags:
        - Batches API v1Alpha
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBatchFastRequest'
      responses:
        '200':
          description: "Successfully created the batch fast."
          content:
            application/json:
              schema:
                type: object
  '/api/v1alpha/batches/{batch_id}/update-fast':
    post:
      summary: "Perform a fast update to a batch"
      description: "Perform a fast batch update without separate create / add content / commit steps"
      operationId: updateBatchFastv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFastUpdateRequest'
      responses:
        '200':
          description: "Successfully updated the batch fast."
          content:
            application/json:
              schema:
                type: object
  '/api/v1alpha/batches/{batch_id}/updates/create':
    post:
      summary: "Create a batch update"
      description: "Create a batch update."
      operationId: createBatchUpdatev1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateRequest'
      responses:
        '200':
          description: "Successfully created the batch update."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpdateResponse'
  '/api/v1alpha/batches/{batch_id}/updates/{update_id}/job-groups/create':
    post:
      summary: "Create a job group"
      description: "Create a job group as part of an update operation."
      operationId: createJobGroupUpdatev1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: update_id
          in: path
          description: "The ID of the update."
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobGroupSpec'
      responses:
        '200':
          description: "Successfully created the job group update."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateJobGroupResponse'
  '/api/v1alpha/batches/{batch_id}/updates/{update_id}/jobs/create':
    post:
      summary: "Create a job"
      description: "Create a job as part of an update operation."
      operationId: createJobUpdatev1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: update_id
          in: path
          description: "The ID of the update."
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '200':
          description: "Successfully created the job update."
          content:
            application/json:
              schema:
                type: object
  '/api/v1alpha/batches/{batch_id}/jobs/create':
    post:
      summary: "Create a job"
      description: "Create a job."
      operationId: createJobv1alpha
      deprecated: true
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '200':
          description: "Successfully created the job."
          content:
            application/json:
              schema:
                type: object
  '/api/v1alpha/batches/{batch_id}/updates/{update_id}/commit':
    post:
      summary: "Commit update"
      description: "Commit an update."
      operationId: commitUpdatev1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: update_id
          in: path
          description: "The ID of the update."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully committed the update."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  '/api/v1alpha/batches/{batch_id}/cancel':
    patch:
      summary: "Cancel batch"
      description: "Cancel a batch."
      operationId: cancelBatchv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully cancelled the batch."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  '/api/v1alpha/batches/{batch_id}/job-groups/{job_group_id}/cancel':
    patch:
      summary: "Cancel job group"
      description: "Cancel a job group."
      operationId: cancelJobGroupv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_group_id
          in: path
          description: "The ID of the job group."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully cancelled the job group."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  '/api/v1alpha/batches/{batch_id}/close':
    patch:
      summary: "Close batch"
      description: "Close a batch."
      operationId: closeBatchv1alpha
      deprecated: true
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully closed the batch."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  '/api/v1alpha/batches/{batch_id}':
    get:
      summary: "Get a batch"
      description: "Get a batch by ID."
      operationId: getBatchv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the batch."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
  '/api/v1alpha/batches/{batch_id}/jobs':
    get:
      summary: "Get all jobs in a batch"
      description: "Get all jobs in a batch by ID."
      operationId: getJobsInBatchv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the jobs in the batch."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
  '/api/v1alpha/batches/{batch_id}/job-groups':
    get:
      summary: "Get all job groups in a batch"
      description: "Get all job groups in a batch by ID."
      operationId: getJobGroupsInBatchv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the job groups in the batch."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobGroupListResponse'
  '/api/v1alpha/batches/{batch_id}/job-groups/{job_group_id}':
    get:
      summary: "Get a job group in a batch"
      description: "Get a job group in a batch by ID."
      operationId: getJobGroupInBatchv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_group_id
          in: path
          description: "The ID of the job group."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the job group in the batch."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobGroupDetailResponse'
  '/api/v1alpha/batches/{batch_id}/job-groups/{job_group_id}/jobs':
    get:
      summary: "Get all jobs in a job group"
      description: "Get all jobs in a job group by ID."
      operationId: getJobsInJobGroupv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_group_id
          in: path
          description: "The ID of the job group."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the jobs in the job group."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
  '/api/v1alpha/batches/{batch_id}/job-groups/{job_group_id}/job-groups':
    get:
      summary: "Get all job groups in a job group"
      description: "Get all job groups in a job group by ID."
      operationId: getJobGroupsInJobGroupv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_group_id
          in: path
          description: "The ID of the job group."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the job groups in the job group."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobGroupListResponse'
  '/api/v1alpha/batches/{batch_id}/jobs/{job_id}':
    get:
      summary: "Get a job in a batch"
      description: "Get a job in a batch by ID."
      operationId: getJobInBatchv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_id
          in: path
          description: "The ID of the job."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the job in the batch."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
  '/api/v1alpha/batches/{batch_id}/jobs/{job_id}/attempts':
    get:
      summary: "Get all attempts in a job"
      description: "Get all attempts in a job by ID."
      operationId: getAttemptsInJobv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_id
          in: path
          description: "The ID of the job."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the attempts in the job."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAttemptsResponse'
  '/api/v1alpha/batches/{batch_id}/jobs/{job_id}/log':
    get:
      summary: "Get job log"
      description: "Get the log of a job by ID."
      operationId: getLogInJobv1alpha
      deprecated: true
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_id
          in: path
          description: "The ID of the job."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the log of the job."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobLogResponse'
  '/api/v1alpha/batches/{batch_id}/jobs/{job_id}/log/{container}':
    get:
      summary: "Get job log by container"
      description: "Get the log of a job from a specific container."
      operationId: getLogInJobContainerV1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_id
          in: path
          description: "The ID of the job."
          required: true
          schema:
            type: number
        - name: container
          in: path
          description: "The name of the container."
          required: true
          schema:
            type: string
        - name: attempt_id
          in: query
          description: "Return the log for a specific attempt. Defaults to the current or most recent attempt."
          required: false
          schema:
            type: string
      responses:
        '200':
          description: "Successfully retrieved the log of the job in the container."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerLogResponse'
  '/api/v1alpha/batches/{batch_id}/jobs/{job_id}/resource_usage':
    get:
      summary: "Get job resource usage"
      description: "Get the resource usage of a job."
      operationId: getResourceUsageInJobv1alpha
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_id
          in: path
          description: "The ID of the job."
          required: true
          schema:
            type: number
        - name: attempt_id
          in: query
          description: "Return resource usage for a specific attempt. Defaults to the current or most recent attempt."
          required: false
          schema:
            type: string
      responses:
        '200':
          description: "Successfully retrieved the resource usage of the job."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceUsageResponse'
  '/api/v2alpha/batches':
    get:
      summary: List batches (v2)
      description: Get a list of batches using v2 query format
      tags: [Batches]
      parameters:
        - name: q
          in: query
          description: Query string in v2 format
          schema:
            type: string
            example: "user = alice"
        - name: last_batch_id
          in: query
          description: Last batch ID for pagination
          schema:
            type: integer
      responses:
        '200':
          description: List of batches retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchListResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - requires developer privileges
  '/api/v2alpha/batches/{batch_id}/jobs':
    get:
      summary: "List jobs in a batch"
      description: "List jobs in a batch by batch ID."
      operationId: getJobsInBatchv2alpha
      tags:
        - Batches API v2Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the jobs in the batch."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobV2ListResponse'
  '/api/v2alpha/batches/{batch_id}/job-groups/{job_group_id}/jobs':
    get:
      summary: "List jobs in a job group"
      description: "List jobs in a job group by job group ID."
      operationId: getJobsInJobGroupv2alpha
      tags:
        - Batches API v2Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_group_id
          in: path
          description: "The ID of the job group."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Successfully retrieved the jobs in the job group."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobV2ListResponse'
  '/api/v1alpha/billing':
    get:
      summary: "Get billing records"
      description: >
        Return per-(billing_project, user) cost records for a date range.
        Non-developers see only their own records; developers see all.
        Costs are plain floats in USD. Omitting `end` includes currently-running batches;
        supplying `end` excludes them.
      operationId: getBilling
      tags:
        - Billing Projects
      parameters:
        - name: start
          in: query
          description: "Start date in MM/DD/YYYY format. Defaults to the first day of the current month."
          required: false
          schema:
            type: string
            example: "04/01/2026"
        - name: end
          in: query
          description: "End date in MM/DD/YYYY format (inclusive, optional). Omit to include currently-running batches."
          required: false
          schema:
            type: string
            example: "04/21/2026"
      responses:
        '200':
          description: "Billing records retrieved successfully."
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BillingRecord'
        '401':
          description: Unauthorized
  '/api/v1alpha/billing_breakdown':
    get:
      summary: "Get billing breakdown"
      description: >
        Return per-(billing_project, user, resource) cost records for a date range.
        Billing managers (READ_ALL_BILLING_PROJECTS) see all records; other users see only
        rows where the user matches their own username. Costs are plain floats in USD.
        Rows with zero cost are excluded. The `resource` field uses internal resource names
        such as `"service-fee"`, `"compute/n1-standard/preemptible/us-central1"`, etc.
      operationId: getBillingBreakdown
      tags:
        - Billing Projects
      parameters:
        - name: start
          in: query
          description: "Start date in MM/DD/YYYY format."
          required: true
          schema:
            type: string
            example: "05/01/2026"
        - name: end
          in: query
          description: "End date in MM/DD/YYYY format (inclusive). Required."
          required: true
          schema:
            type: string
            example: "05/31/2026"
      responses:
        '200':
          description: "Billing breakdown retrieved successfully."
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BillingBreakdownRecord'
        '400':
          description: "Missing or invalid date parameters."
        '401':
          description: Unauthorized
  '/api/v1alpha/billing_projects':
    get:
      summary: "List billing projects"
      description: "List billing projects. Optionally filter by status."
      operationId: getBillingProjects
      tags:
        - Billing Projects
      parameters:
        - name: status
          in: query
          description: "Filter by billing project status. If omitted, returns both open and closed projects."
          required: false
          schema:
            type: string
            enum: [open, closed]
      responses:
        '200':
          description: "Successfully retrieved the billing projects."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProjectListResponse'
        '400':
          description: "Invalid status value."
  '/api/v1alpha/billing_projects/{billing_project}':
    get:
      summary: "Get a billing project"
      description: "Get a billing project by ID."
      operationId: getBillingProject
      tags:
        - Billing Projects
      parameters:
        - name: billing_project
          in: path
          description: "The ID of the billing project."
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Successfully retrieved the billing project."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProjectResponse'
  '/api/v1alpha/billing_projects/{billing_project}/create':
    post:
      summary: Create billing project
      description: Create a new billing project
      tags: [Billing]
      parameters:
        - name: billing_project
          in: path
          required: true
          schema:
            type: string
          description: Billing project identifier
      responses:
        '200':
          description: Billing project created successfully
          content:
            application/json:
              schema:
                type: string
                description: Created billing project identifier
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - requires developer privileges
        '409':
          description: Billing project already exists
  '/api/v1alpha/billing_projects/{billing_project}/users/{user}/add':
    post:
      summary: "Add a user to a billing project"
      description: "Add a user to a billing project."
      operationId: addUserToBillingProject
      tags:
        - Billing Projects
      parameters:
        - name: billing_project
          in: path
          description: "The ID of the billing project."
          required: true
          schema:
            type: string
        - name: user
          in: path
          description: "The username of the user."
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Successfully added the user to the billing project."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  '/api/v1alpha/billing_projects/{billing_project}/users/{user}/remove':
    post:
      summary: "Remove a user from a billing project"
      description: "Remove a user from a billing project."
      operationId: removeUserFromBillingProject
      tags:
        - Billing Projects
      parameters:
        - name: billing_project
          in: path
          description: "The ID of the billing project."
          required: true
          schema:
            type: string
        - name: user
          in: path
          description: "The username of the user."
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Successfully removed the user from the billing project."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  '/api/v1alpha/billing_projects/{billing_project}/close':
    post:
      summary: "Close billing project"
      description: "Close a billing project."
      operationId: closeBillingProject
      tags:
        - Billing Projects
      parameters:
        - name: billing_project
          in: path
          description: "The ID of the billing project."
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Successfully closed the billing project."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  '/api/v1alpha/billing_projects/{billing_project}/reopen':
    post:
      summary: "Reopen billing project"
      description: "Reopen a billing project."
      operationId: reopenBillingProject
      tags:
        - Billing Projects
      parameters:
        - name: billing_project
          in: path
          description: "The ID of the billing project."
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Successfully reopened the billing project."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  '/api/v1alpha/billing_projects/{billing_project}/delete':
    post:
      summary: Delete billing project
      description: Delete an existing billing project
      tags: [Billing]
      parameters:
        - name: billing_project
          in: path
          required: true
          schema:
            type: string
          description: Billing project identifier
      responses:
        '200':
          description: Billing project deleted successfully
          content:
            application/json:
              schema:
                type: string
                description: Deleted billing project identifier
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - requires developer privileges
        '404':
          description: Billing project not found
  '/api/v1alpha/billing_limits/{billing_project}/edit':
    post:
      summary: Edit billing limits
      description: Edit billing limits for a billing project
      tags: [Billing]
      parameters:
        - name: billing_project
          in: path
          required: true
          schema:
            type: string
          description: Billing project identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: number
                  description: New billing limit
      responses:
        '200':
          description: Billing limit updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  billing_project:
                    type: string
                    description: Billing project identifier
                  limit:
                    type: number
                    description: Updated billing limit
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - requires developer privileges
        '404':
          description: Billing project not found
  '/api/v1alpha/batches/{batch_id}/jobs/{job_id}/jvm_profile':
    get:
      summary: "Get JVM profile data"
      description: "Get raw JVM profiling data for a completed job. Only available for jobs run with profiling enabled."
      operationId: getJvmProfile
      tags:
        - Batches API v1Alpha
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_id
          in: path
          description: "The ID of the job."
          required: true
          schema:
            type: number
      responses:
        '200':
          description: "Raw JVM profile data."
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: "Profile not available (job not complete, profiling not enabled, or profile not yet uploaded)."
  '/batches':
    get:
      summary: "Batches page (UI)"
      description: "Render the batches page, or (dev only) its supporting jinja context"
      operationId: getBatchesUI
      tags:
        - UI Support
      parameters:
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the batches."
          content:
            application/json:
              schema:
                type: object
  '/batches/{batch_id}':
    get:
      summary: "Batch page (UI)"
      description: "Render the batch page, or (dev only) its supporting jinja context"
      operationId: getBatchUI
      tags:
        - UI Support
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the batch."
          content:
            application/json:
              schema:
                type: object
  '/batches/{batch_id}/cancel':
    post:
      summary: "Cancel batch (UI)"
      description: "Cancel a batch and render the result, or (dev only) its supporting jinja context"
      operationId: cancelBatchUI
      tags:
        - UI Support
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
              type: boolean
              default: false
              example: true
      responses:
        '200':
          description: "Successfully cancelled the batch."
          content:
            application/json:
              schema:
                type: object
  '/batches/{batch_id}/delete':
    post:
      summary: "Delete batch (UI)"
      description: "Delete a batch and render a result HTML, or (dev only) its supporting jinja context"
      operationId: deleteBatchUI
      tags:
        - UI Support
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
              type: boolean
              default: false
              example: true
      responses:
        '200':
          description: "Successfully deleted the batch."
          content:
            application/json:
              schema:
                type: object
  '/batches/{batch_id}/jobs/{job_id}':
    get:
      summary: "Job page (UI)"
      description: "Render the job page, or (dev only) its supporting jinja context"
      operationId: getJobUI
      tags:
        - UI Support
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_id
          in: path
          description: "The ID of the job."
          required: true
          schema:
            type: number
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the job."
          content:
            application/json:
              schema:
                type: object
  '/batches/{batch_id}/jobs/{job_id}/jvm_profile':
    get:
      summary: "Job JVM profile page (UI)"
      description: "Render the job JVM profile page, or (dev only) its supporting jinja context"
      operationId: getJobJVMProfileUI
      tags:
        - UI Support
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_id
          in: path
          description: "The ID of the job."
          required: true
          schema:
            type: number
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the job JVM profile."
          content:
            application/json:
              schema:
                type: object
  '/batches/{batch_id}/jobs/{job_id}/log/{container}':
    get:
      summary: "Job log page (UI)"
      description: "Render the job log page, or (dev only) its supporting jinja context"
      operationId: getJobLogUI
      tags:
        - UI Support
      parameters:
        - name: batch_id
          in: path
          description: "The ID of the batch."
          required: true
          schema:
            type: number
        - name: job_id
          in: path
          description: "The ID of the job."
          required: true
          schema:
            type: number
        - name: container
          in: path
          description: "The name of the container."
          required: true
          schema:
            type: string
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the job log."
          content:
            application/json:
              schema:
                type: object
  '/billing':
    get:
      summary: "Billing page (UI)"
      description: "Render the billing page, or (dev only) its supporting jinja context"
      operationId: getBillingUI
      tags:
        - UI Support
      parameters:
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the billing page."
          content:
            application/json:
              schema:
                type: object
  '/billing_limits':
    get:
      summary: "Billing limits page (UI)"
      description: "Render the billing limits page, or (dev only) its supporting jinja context"
      operationId: getBillingLimitsUI
      tags:
        - UI Support
      parameters:
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the billing limits page."
          content:
            application/json:
              schema:
                type: object
  '/billing_limits/{billing_project}/edit':
    post:
      summary: Edit billing limits
      description: Edit billing limits for a billing project
      tags: [Billing]
      parameters:
        - name: billing_project
          in: path
          required: true
          schema:
            type: string
          description: Billing project identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: number
                  description: New billing limit
      responses:
        '200':
          description: Billing limit updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  billing_project:
                    type: string
                    description: Billing project identifier
                  limit:
                    type: number
                    description: Updated billing limit
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - requires developer privileges
        '404':
          description: Billing project not found
  '/billing_projects':
    get:
      summary: "Billing projects page (UI)"
      description: "Render the billing projects page, or (dev only) its supporting jinja context"
      operationId: getBillingProjectsUI
      tags:
        - UI Support
      parameters:
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the billing projects page."
          content:
            application/json:
              schema:
                type: object
  '/billing_projects/create':
    post:
      summary: Create billing project
      description: Create a new billing project
      tags: [Billing]
      parameters:
        - name: billing_project
          in: path
          required: true
          schema:
            type: string
          description: Billing project identifier
      responses:
        '200':
          description: Billing project created successfully
          content:
            application/json:
              schema:
                type: string
                description: Created billing project identifier
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - requires developer privileges
        '409':
          description: Billing project already exists
  '/billing_projects/{billing_project}/users/add':
    post:
      summary: "Add user to billing project element (UI)"
      description: "Add a user to a billing project and return rendered result HTML, or (dev only) its supporting jinja context"
      operationId: addUserToBillingProjectUI
      tags:
        - Billing Projects
      parameters:
        - name: billing_project
          in: path
          description: "The ID of the billing project."
          required: true
          schema:
            type: string
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully added the user to the billing project."
          content:
            application/json:
              schema:
                type: object
  '/billing_projects/{billing_project}/users/{user}/remove':
    post:
      summary: "Remove user from billing project element (UI)"
      description: "Remove a user from a billing project and return rendered result HTML, or (dev only) its supporting jinja context"
      operationId: removeUserFromBillingProjectUI
      tags:
        - Billing Projects
      parameters:
        - name: billing_project
          in: path
          description: "The ID of the billing project."
          required: true
          schema:
            type: string
        - name: user
          in: path
          description: "The username of the user."
          required: true
          schema:
            type: string
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully removed the user from the billing project."
          content:
            application/json:
              schema:
                type: object
  '/billing_projects/{billing_project}/close':
    post:
      summary: "Close billing project element (UI)"
      description: "Close a billing project and return rendered result HTML, or (dev only) its supporting jinja context"
      operationId: closeBillingProjectUI
      tags:
        - Billing Projects
      parameters:
        - name: billing_project
          in: path
          description: "The ID of the billing project."
          required: true
          schema:
            type: string
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully closed the billing project."
          content:
            application/json:
              schema:
                type: object
  '/billing_projects/{billing_project}/reopen':
    post:
      summary: "Reopen billing project element (UI)"
      description: "Reopen a billing project and return rendered result HTML, or (dev only) its supporting jinja context"
      operationId: reopenBillingProjectUI
      tags:
        - Billing Projects
      parameters:
        - name: billing_project
          in: path
          description: "The ID of the billing project."
          required: true
          schema:
            type: string
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully reopened the billing project."
          content:
            application/json:
              schema:
                type: object
  '/openapi.yaml':
    get:
      summary: "OpenAPI spec"
      description: "Render the OpenAPI spec, or (dev only) its supporting jinja context"
      operationId: getOpenAPI
      tags:
        - UI Support
      parameters:
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the OpenAPI spec."
          content:
            application/json:
              schema:
                type: object
  '/swagger':
    get:
      summary: "Swagger UI"
      description: "Render the swagger UI page, or (dev only) its supporting jinja context"
      operationId: getSwaggerUi
      tags:
        - UI Support
      parameters:
        - name: x-hail-return-jinja-context
          in: header
          description: "Do not render, and instead return the jinja context json."
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: "Successfully retrieved the Swagger UI"
          content:
            application/json:
              schema:
                type: object

components:
  schemas:
    BillingLimitRequest:
      type: object
      required:
        - limit
      properties:
        limit:
          type: number
          description: "The billing limit value in dollars. Use null to remove the limit."
          nullable: true
          example: 1000.50

    CreateBatchRequest:
      type: object
      required:
        - billing_project
        - attributes
      properties:
        billing_project:
          type: string
          description: "The billing project to charge for this batch"
        attributes:
          type: object
          description: "Key-value pairs of attributes for the batch"
          additionalProperties:
            type: string
        callback:
          type: string
          description: "Optional callback URL to notify when batch completes"
        token:
          type: string
          description: "Optional token for batch identification"
        cancel_after_n_failures:
          type: integer
          description: "Optional number of failures after which to cancel the batch"
          minimum: 1

    CreateJobRequest:
      type: object
      required:
        - job_spec
      properties:
        job_spec:
          type: object
          required:
            - command
          properties:
            command:
              type: array
              items:
                type: string
              description: "Command to execute"
            env:
              type: object
              additionalProperties:
                type: string
              description: "Environment variables"
            port:
              type: integer
              description: "Port to expose"
            resources:
              type: object
              properties:
                cpu:
                  type: string
                memory:
                  type: string
                storage:
                  type: string
            service_account:
              type: object
              properties:
                namespace:
                  type: string
                name:
                  type: string
            timeout:
              type: integer
              description: "Job timeout in seconds"
            attributes:
              type: object
              additionalProperties:
                type: string
              description: "Job attributes"
            callback:
              type: string
              description: "Callback URL"

    CreateBillingProjectRequest:
      type: object
      properties:
        budget:
          type: number
          description: "Initial budget for the billing project"

    BatchUpdateRequest:
      type: object
      required:
        - update_token
      properties:
        update_token:
          type: string
          description: "Token to identify this update"
        job_specs:
          type: array
          description: "List of job specifications to add"
          items:
            $ref: '#/components/schemas/CreateJobRequest'
        job_groups:
          type: array
          description: "List of job groups to add"
          items:
            $ref: '#/components/schemas/JobGroupSpec'

    JobGroupSpec:
      type: object
      required:
        - attributes
      properties:
        attributes:
          type: object
          description: "Key-value pairs of attributes for the job group"
          additionalProperties:
            type: string
        cancel_after_n_failures:
          type: integer
          description: "Optional number of failures after which to cancel the job group"
          minimum: 1
        callback:
          type: string
          description: "Optional callback URL to notify when job group completes"

    BatchFastUpdateRequest:
      type: object
      required:
        - job_specs
      properties:
        job_specs:
          type: array
          description: "List of job specifications to add"
          items:
            $ref: '#/components/schemas/CreateJobRequest'
        job_groups:
          type: array
          description: "List of job groups to add"
          items:
            $ref: '#/components/schemas/JobGroupSpec'

    CreateBatchFastRequest:
      type: object
      required:
        - billing_project
        - token
        - attributes
        - job_specs
      properties:
        billing_project:
          type: string
          description: "The billing project to charge for this batch"
        token:
          type: string
          description: "Token for batch identification"
        attributes:
          type: object
          description: "Key-value pairs of attributes for the batch"
          additionalProperties:
            type: string
        callback:
          type: string
          description: "Optional callback URL to notify when batch completes"
        cancel_after_n_failures:
          type: integer
          description: "Optional number of failures after which to cancel the batch"
          minimum: 1
        job_specs:
          type: array
          description: "List of job specifications"
          items:
            $ref: '#/components/schemas/CreateJobRequest'
        job_groups:
          type: array
          description: "List of job groups"
          items:
            $ref: '#/components/schemas/JobGroupSpec'

    BatchResponse:
      type: object
      properties:
        id:
          type: integer
          description: "The batch ID"
        user:
          type: string
          description: "The user who created the batch"
        billing_project:
          type: string
          description: "The billing project associated with the batch"
        token:
          type: string
          description: "Token for batch identification"
        state:
          type: string
          enum: ["open", "complete", "cancelled", "failure", "running"]
          description: "Current state of the batch"
        complete:
          type: boolean
          description: "Whether the batch is complete"
        closed:
          type: boolean
          description: "Whether the batch is closed"
        n_jobs:
          type: integer
          description: "Total number of jobs in the batch"
        n_completed:
          type: integer
          description: "Number of completed jobs"
        n_succeeded:
          type: integer
          description: "Number of succeeded jobs"
        n_failed:
          type: integer
          description: "Number of failed jobs"
        n_cancelled:
          type: integer
          description: "Number of cancelled jobs"
        time_created:
          type: string
          format: date-time
          description: "When the batch was created"
        time_completed:
          type: string
          format: date-time
          description: "When the batch completed"
          nullable: true
        attributes:
          type: object
          description: "Key-value pairs of attributes for the batch"
          additionalProperties:
            type: string

    CostBreakdownEntry:
      type: object
      properties:
        resource:
          type: string
          description: "Name of the resource"
        cost:
          type: number
          description: "Cost for this resource in USD"

    JobResponse:
      type: object
      properties:
        batch_id:
          type: integer
          description: "ID of the batch this job belongs to"
        job_id:
          type: integer
          description: "The job ID"
        job_group_id:
          type: integer
          description: "ID of the job group this job belongs to"
        name:
          type: string
          description: "Name of the job"
          nullable: true
        user:
          type: string
          description: "User who owns the job"
        billing_project:
          type: string
          description: "Billing project for the job"
        state:
          type: string
          enum: ["Pending", "Ready", "Creating", "Running", "Failed", "Cancelled", "Error", "Success"]
          description: "Current state of the job"
        display_state:
          type: string
          description: "Human-readable display state"
          nullable: true
        exit_code:
          type: integer
          description: "Exit code of the job"
          nullable: true
        duration:
          type: number
          description: "Duration of the job in milliseconds"
          nullable: true
        start_time:
          type: string
          format: date-time
          description: "When the job started"
          nullable: true
        end_time:
          type: string
          format: date-time
          description: "When the job ended"
          nullable: true
        cost:
          type: number
          description: "Total cost of the job in USD"
          nullable: true
        msec_mcpu:
          type: integer
          description: "Millisecond milli-CPU usage"
        cost_breakdown:
          type: array
          description: "Per-resource cost breakdown"
          items:
            $ref: '#/components/schemas/CostBreakdownEntry'
        always_run:
          type: boolean
          description: "Whether the job runs regardless of the batch's success state"
        n_max_attempts:
          type: integer
          description: "Maximum number of times this job will be attempted"
        inst_coll:
          type: string
          description: "Instance collection the job ran on"
          nullable: true
        attributes:
          type: object
          description: "Key-value pairs of attributes for the job"
          additionalProperties:
            type: string
          nullable: true
        status:
          type: object
          description: "Detailed job status"
          nullable: true
        spec:
          $ref: '#/components/schemas/CreateJobRequest'

    JobGroupResponse:
      type: object
      properties:
        batch_id:
          type: integer
          description: "ID of the batch this job group belongs to"
        job_group_id:
          type: integer
          description: "The job group ID"
        state:
          type: string
          enum: ["running", "complete", "cancelled"]
          description: "Current state of the job group"
        complete:
          type: boolean
          description: "Whether the job group is complete"
        n_jobs:
          type: integer
          description: "Total number of jobs in the group"
        n_completed:
          type: integer
          description: "Number of completed jobs"
        n_succeeded:
          type: integer
          description: "Number of succeeded jobs"
        n_failed:
          type: integer
          description: "Number of failed jobs"
        n_cancelled:
          type: integer
          description: "Number of cancelled jobs"
        time_created:
          type: string
          format: date-time
          description: "When the job group was created"
        attributes:
          type: object
          description: "Key-value pairs of attributes for the job group"
          additionalProperties:
            type: string

    BatchListResponse:
      type: object
      properties:
        batches:
          type: array
          items:
            $ref: '#/components/schemas/BatchResponse'
        last_batch_id:
          type: integer
          description: "ID of the last batch in the list for pagination"
          nullable: true

    JobListResponse:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/JobResponse'
        last_job_id:
          type: integer
          description: "ID of the last job in the list for pagination"
          nullable: true

    JobGroupListResponse:
      type: object
      properties:
        job_groups:
          type: array
          items:
            $ref: '#/components/schemas/JobGroupResponse'
        last_job_group_id:
          type: integer
          description: "ID of the last job group in the list for pagination"
          nullable: true

    BillingProjectResponse:
      type: object
      properties:
        name:
          type: string
          description: "Name of the billing project"
        status:
          type: string
          enum: ["open", "closed"]
          description: "Status of the billing project"
        users:
          type: array
          items:
            type: string
          description: "List of users with access to this billing project"
        limit:
          type: number
          description: "Billing limit in dollars"
          nullable: true

    BillingProjectListResponse:
      type: object
      properties:
        billing_projects:
          type: array
          items:
            $ref: '#/components/schemas/BillingProjectResponse'

    JobAttemptResponse:
      type: object
      properties:
        attempt_id:
          type: string
          description: "ID of the attempt"
        instance_name:
          type: string
          description: "Name of the instance that ran the attempt"
        start_time:
          type: string
          format: date-time
          description: "When the attempt started"
        end_time:
          type: string
          format: date-time
          description: "When the attempt ended"
          nullable: true
        reason:
          type: string
          description: "Reason for the attempt status"
          nullable: true
        status:
          type: string
          enum: ["pending", "running", "succeeded", "failed", "error"]
          description: "Status of the attempt"

    JobAttemptsResponse:
      type: object
      properties:
        attempts:
          type: array
          items:
            $ref: '#/components/schemas/JobAttemptResponse'

    ResourceUsageResponse:
      type: object
      properties:
        cpu_usage:
          type: array
          items:
            type: object
            properties:
              time:
                type: string
                format: date-time
              usage:
                type: number
          description: "CPU usage over time"
        memory_usage:
          type: array
          items:
            type: object
            properties:
              time:
                type: string
                format: date-time
              usage:
                type: number
          description: "Memory usage over time"
        storage_usage:
          type: array
          items:
            type: object
            properties:
              time:
                type: string
                format: date-time
              usage:
                type: number
          description: "Storage usage over time"

    BatchUpdateResponse:
      type: object
      properties:
        update_id:
          type: integer
          description: "ID of the created update"
        token:
          type: string
          description: "Token associated with the update"

    JobLogResponse:
      type: object
      properties:
        main:
          type: string
          description: "Log output from the main container"
          nullable: true
        input:
          type: string
          description: "Log output from the input container"
          nullable: true
        setup:
          type: string
          description: "Log output from the setup container"
          nullable: true
        output:
          type: string
          description: "Log output from the output container"
          nullable: true

    ContainerLogResponse:
      type: object
      properties:
        log:
          type: string
          description: "Log output from the specified container"

    BatchV2Response:
      type: object
      properties:
        id:
          type: integer
          description: "The batch ID"
        user:
          type: string
          description: "The user who created the batch"
        billing_project:
          type: string
          description: "The billing project associated with the batch"
        token:
          type: string
          description: "Token for batch identification"
        state:
          type: string
          enum: ["open", "complete", "cancelled", "failure", "running"]
          description: "Current state of the batch"
        complete:
          type: boolean
          description: "Whether the batch is complete"
        n_jobs:
          type: integer
          description: "Total number of jobs in the batch"
        cost:
          type: number
          description: "Total cost of the batch"
          nullable: true
        time_created:
          type: string
          format: date-time
          description: "When the batch was created"
        time_completed:
          type: string
          format: date-time
          description: "When the batch completed"
          nullable: true
        attributes:
          type: object
          description: "Key-value pairs of attributes for the batch"
          additionalProperties:
            type: string

    BatchV2ListResponse:
      type: object
      properties:
        batches:
          type: array
          items:
            $ref: '#/components/schemas/BatchV2Response'
        last_batch_id:
          type: integer
          description: "ID of the last batch in the list for pagination"
          nullable: true

    JobV2Response:
      type: object
      properties:
        batch_id:
          type: integer
          description: "ID of the batch this job belongs to"
        job_id:
          type: integer
          description: "The job ID"
        state:
          type: string
          enum: ["pending", "running", "succeeded", "failed", "cancelled"]
          description: "Current state of the job"
        exit_code:
          type: integer
          description: "Exit code of the job"
          nullable: true
        duration:
          type: number
          description: "Duration of the job in seconds"
          nullable: true
        cost:
          type: number
          description: "Cost of the job"
          nullable: true
        start_time:
          type: string
          format: date-time
          description: "When the job started"
          nullable: true
        end_time:
          type: string
          format: date-time
          description: "When the job ended"
          nullable: true
        attributes:
          type: object
          description: "Key-value pairs of attributes for the job"
          additionalProperties:
            type: string
        spec:
          $ref: '#/components/schemas/CreateJobRequest'

    JobV2ListResponse:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/JobV2Response'
        last_job_id:
          type: integer
          description: "ID of the last job in the list for pagination"
          nullable: true

    VersionResponse:
      type: string
      description: "Version of the service"
      example: "0.2.133"

    CloudProviderResponse:
      type: string
      description: "Cloud provider supported by this batch instance"
      enum: ["gcp", "azure", "aws"]
      example: "gcp"

    SupportedRegionsResponse:
      type: array
      description: "List of supported regions"
      items:
        type: string
        description: "Region identifier"

    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: "Whether the operation was successful"
          example: true

    JobGroupDetailResponse:
      type: object
      properties:
        batch_id:
          type: integer
          description: "ID of the batch this job group belongs to"
        job_group_id:
          type: integer
          description: "The job group ID"
        parent_job_group_id:
          type: integer
          description: "ID of the parent job group"
          nullable: true
        state:
          type: string
          enum: ["running", "complete", "cancelled"]
          description: "Current state of the job group"
        complete:
          type: boolean
          description: "Whether the job group is complete"
        n_jobs:
          type: integer
          description: "Total number of jobs in the group"
        n_completed:
          type: integer
          description: "Number of completed jobs"
        n_succeeded:
          type: integer
          description: "Number of succeeded jobs"
        n_failed:
          type: integer
          description: "Number of failed jobs"
        n_cancelled:
          type: integer
          description: "Number of cancelled jobs"
        time_created:
          type: string
          format: date-time
          description: "When the job group was created"
        attributes:
          type: object
          description: "Key-value pairs of attributes for the job group"
          additionalProperties:
            type: string
        children:
          type: array
          description: "List of child job groups"
          items:
            $ref: '#/components/schemas/JobGroupResponse'

    BillingRecord:
      type: object
      properties:
        billing_project:
          type: string
          description: "The billing project."
        user:
          type: string
          description: "The user."
        total_spent:
          type: number
          description: "Total cost in USD."

    BillingBreakdownRecord:
      type: object
      properties:
        billing_project:
          type: string
          description: "The billing project."
        user:
          type: string
          description: "The user."
        resource:
          type: string
          description: "Internal resource name (e.g. 'service-fee', 'compute/n1-standard/preemptible/us-central1')."
        cost:
          type: number
          description: "Cost in USD for this (billing_project, user, resource) combination."

    CreateJobGroupResponse:
      type: object
      properties:
        job_group_id:
          type: integer
          description: "ID of the created job group"