Red Hat Job Templates API

openapi: 3.1.0
info:
  title: Red Hat Ansible Automation Platform Add-Ons Job Templates API
  description: The Red Hat Ansible Automation Platform API provides programmatic access to the automation controller for managing IT infrastructure automation. It supports creating and launching job templates, managing inventories, tracking job execution status, and configuring credentials for connecting to managed hosts and external services.
  version: '2.6'
  contact:
    name: Red Hat Support
    url: https://access.redhat.com/support
  termsOfService: https://www.redhat.com/en/about/terms-use
servers:
- url: https://ansible-platform.example.com
  description: Ansible Automation Platform Server
security:
- bearerAuth: []
tags:
- name: Job Templates
  description: Operations for managing job templates that define parameterized playbook runs against inventories of managed hosts.
paths:
  /api/v2/job_templates/:
    get:
      operationId: listJobTemplates
      summary: Red Hat List Job Templates
      description: Retrieves a paginated list of job templates. Job templates define the parameters for running Ansible playbooks against specified inventories, including the project, playbook, credentials, and extra variables.
      tags:
      - Job Templates
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      - $ref: '#/components/parameters/SearchParam'
      - $ref: '#/components/parameters/OrderingParam'
      responses:
        '200':
          description: Successfully retrieved job templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedJobTemplateList'
              examples:
                Listjobtemplates200Example:
                  summary: Default listJobTemplates 200 response
                  x-microcks-default: true
                  value:
                    count: 10
                    next: https://www.example.com
                    previous: https://www.example.com
                    results:
                    - id: abc123
                      name: Example Title
                      description: A sample description.
                      job_type: run
                      inventory: 10
                      project: 10
                      playbook: example_value
                      forks: 10
                      limit: example_value
                      verbosity: 0
                      extra_vars: example_value
                      ask_variables_on_launch: true
                      ask_inventory_on_launch: true
                      ask_credential_on_launch: true
                      survey_enabled: true
                      created: '2026-01-15T10:30:00Z'
                      modified: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createJobTemplate
      summary: Red Hat Create a Job Template
      description: Creates a new job template with the specified configuration. Requires at minimum a name, project, playbook, and inventory reference.
      tags:
      - Job Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobTemplate'
            examples:
              CreatejobtemplateRequestExample:
                summary: Default createJobTemplate request
                x-microcks-default: true
                value:
                  id: abc123
                  name: Example Title
                  description: A sample description.
                  job_type: run
                  inventory: 10
                  project: 10
                  playbook: example_value
                  forks: 10
                  limit: example_value
                  verbosity: 0
                  extra_vars: example_value
                  ask_variables_on_launch: true
                  ask_inventory_on_launch: true
                  ask_credential_on_launch: true
                  survey_enabled: true
                  created: '2026-01-15T10:30:00Z'
                  modified: '2026-01-15T10:30:00Z'
      responses:
        '201':
          description: Job template created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobTemplate'
              examples:
                Createjobtemplate201Example:
                  summary: Default createJobTemplate 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    description: A sample description.
                    job_type: run
                    inventory: 10
                    project: 10
                    playbook: example_value
                    forks: 10
                    limit: example_value
                    verbosity: 0
                    extra_vars: example_value
                    ask_variables_on_launch: true
                    ask_inventory_on_launch: true
                    ask_credential_on_launch: true
                    survey_enabled: true
                    created: '2026-01-15T10:30:00Z'
                    modified: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/job_templates/{id}/:
    get:
      operationId: getJobTemplate
      summary: Red Hat Get a Job Template
      description: Retrieves the details of a specific job template by its identifier.
      tags:
      - Job Templates
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Successfully retrieved job template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobTemplate'
              examples:
                Getjobtemplate200Example:
                  summary: Default getJobTemplate 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    description: A sample description.
                    job_type: run
                    inventory: 10
                    project: 10
                    playbook: example_value
                    forks: 10
                    limit: example_value
                    verbosity: 0
                    extra_vars: example_value
                    ask_variables_on_launch: true
                    ask_inventory_on_launch: true
                    ask_credential_on_launch: true
                    survey_enabled: true
                    created: '2026-01-15T10:30:00Z'
                    modified: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateJobTemplate
      summary: Red Hat Update a Job Template
      description: Updates an existing job template. Only the fields provided in the request body will be modified.
      tags:
      - Job Templates
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobTemplate'
            examples:
              UpdatejobtemplateRequestExample:
                summary: Default updateJobTemplate request
                x-microcks-default: true
                value:
                  id: abc123
                  name: Example Title
                  description: A sample description.
                  job_type: run
                  inventory: 10
                  project: 10
                  playbook: example_value
                  forks: 10
                  limit: example_value
                  verbosity: 0
                  extra_vars: example_value
                  ask_variables_on_launch: true
                  ask_inventory_on_launch: true
                  ask_credential_on_launch: true
                  survey_enabled: true
                  created: '2026-01-15T10:30:00Z'
                  modified: '2026-01-15T10:30:00Z'
      responses:
        '200':
          description: Job template updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobTemplate'
              examples:
                Updatejobtemplate200Example:
                  summary: Default updateJobTemplate 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    description: A sample description.
                    job_type: run
                    inventory: 10
                    project: 10
                    playbook: example_value
                    forks: 10
                    limit: example_value
                    verbosity: 0
                    extra_vars: example_value
                    ask_variables_on_launch: true
                    ask_inventory_on_launch: true
                    ask_credential_on_launch: true
                    survey_enabled: true
                    created: '2026-01-15T10:30:00Z'
                    modified: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteJobTemplate
      summary: Red Hat Delete a Job Template
      description: Deletes a job template. Associated job runs will not be deleted but will no longer be linked to a template.
      tags:
      - Job Templates
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '204':
          description: Job template deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/job_templates/{id}/launch/:
    post:
      operationId: launchJobTemplate
      summary: Red Hat Launch a Job Template
      description: Launches a job from the specified job template. Optional extra variables, credentials, and inventory overrides can be provided in the request body. Returns the created job record with its identifier for tracking execution progress.
      tags:
      - Job Templates
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                extra_vars:
                  type: object
                  description: Additional variables to pass to the playbook run.
                inventory:
                  type: integer
                  description: Override inventory for this job launch.
                credentials:
                  type: array
                  description: Override credentials for this job launch.
                  items:
                    type: integer
                limit:
                  type: string
                  description: Host pattern to further limit the inventory.
                tags:
                  type: string
                  description: Comma-separated list of playbook tags to run.
            examples:
              LaunchjobtemplateRequestExample:
                summary: Default launchJobTemplate request
                x-microcks-default: true
                value:
                  extra_vars: example_value
                  inventory: 10
                  credentials:
                  - 10
                  limit: example_value
                  tags: example_value
      responses:
        '201':
          description: Job launched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
              examples:
                Launchjobtemplate201Example:
                  summary: Default launchJobTemplate 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    status: new
                    failed: true
                    started: '2026-01-15T10:30:00Z'
                    finished: '2026-01-15T10:30:00Z'
                    elapsed: 42.5
                    job_template: 10
                    inventory: 10
                    project: 10
                    playbook: example_value
                    launch_type: manual
                    created: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      description: The unique numeric identifier of the resource.
      schema:
        type: integer
    OrderingParam:
      name: ordering
      in: query
      description: The field to use for ordering results. Prefix with a dash for descending order (e.g., -created).
      schema:
        type: string
    PageParam:
      name: page
      in: query
      description: The page number for paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
    SearchParam:
      name: search
      in: query
      description: A search term to filter results by name or description.
      schema:
        type: string
    PageSizeParam:
      name: page_size
      in: query
      description: The number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 25
  schemas:
    Job:
      type: object
      description: A job represents a single execution of a job template, tracking the playbook run status, timing, and output.
      properties:
        id:
          type: integer
          description: The unique identifier of the job.
          example: abc123
        name:
          type: string
          description: The name of the job.
          example: Example Title
        status:
          type: string
          description: The current execution status of the job.
          enum:
          - new
          - pending
          - waiting
          - running
          - successful
          - failed
          - error
          - canceled
          example: new
        failed:
          type: boolean
          description: Whether the job execution failed.
          example: true
        started:
          type: string
          format: date-time
          description: When the job execution started.
          example: '2026-01-15T10:30:00Z'
        finished:
          type: string
          format: date-time
          description: When the job execution finished.
          example: '2026-01-15T10:30:00Z'
        elapsed:
          type: number
          format: float
          description: The elapsed time in seconds for job execution.
          example: 42.5
        job_template:
          type: integer
          description: The ID of the job template that was executed.
          example: 10
        inventory:
          type: integer
          description: The ID of the inventory used for this job.
          example: 10
        project:
          type: integer
          description: The ID of the project used for this job.
          example: 10
        playbook:
          type: string
          description: The playbook that was executed.
          example: example_value
        launch_type:
          type: string
          description: How the job was launched.
          enum:
          - manual
          - relaunch
          - callback
          - scheduled
          - dependency
          - workflow
          - sync
          - scm
          example: manual
        created:
          type: string
          format: date-time
          description: The date and time the job record was created.
          example: '2026-01-15T10:30:00Z'
    PaginatedJobTemplateList:
      type: object
      description: A paginated list of job templates.
      properties:
        count:
          type: integer
          description: The total number of results.
          example: 10
        next:
          type: string
          format: uri
          nullable: true
          description: URL to the next page of results.
          example: https://www.example.com
        previous:
          type: string
          format: uri
          nullable: true
          description: URL to the previous page of results.
          example: https://www.example.com
        results:
          type: array
          items:
            $ref: '#/components/schemas/JobTemplate'
          example: []
    JobTemplate:
      type: object
      description: A job template defines the parameters for running an Ansible playbook against an inventory of managed hosts.
      properties:
        id:
          type: integer
          description: The unique identifier of the job template.
          example: abc123
        name:
          type: string
          description: The name of the job template.
          example: Example Title
        description:
          type: string
          description: A description of the job template.
          example: A sample description.
        job_type:
          type: string
          description: The type of job to execute.
          enum:
          - run
          - check
          example: run
        inventory:
          type: integer
          description: The ID of the inventory to run against.
          example: 10
        project:
          type: integer
          description: The ID of the project containing the playbook.
          example: 10
        playbook:
          type: string
          description: The playbook filename to execute from the project.
          example: example_value
        forks:
          type: integer
          description: The number of parallel processes to use for execution.
          default: 0
          example: 10
        limit:
          type: string
          description: A host pattern to further limit the inventory scope.
          example: example_value
        verbosity:
          type: integer
          description: The verbosity level for job output (0-5).
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
          default: 0
          example: 0
        extra_vars:
          type: string
          description: Extra variables in YAML or JSON format.
          example: example_value
        ask_variables_on_launch:
          type: boolean
          description: Whether to prompt for extra variables on launch.
          example: true
        ask_inventory_on_launch:
          type: boolean
          description: Whether to prompt for inventory on launch.
          example: true
        ask_credential_on_launch:
          type: boolean
          description: Whether to prompt for credentials on launch.
          example: true
        survey_enabled:
          type: boolean
          description: Whether the survey is enabled for this template.
          example: true
        created:
          type: string
          format: date-time
          description: The date and time the template was created.
          example: '2026-01-15T10:30:00Z'
        modified:
          type: string
          format: date-time
          description: The date and time the template was last modified.
          example: '2026-01-15T10:30:00Z'
    Error:
      type: object
      description: An error response from the API.
      properties:
        detail:
          type: string
          description: A human-readable description of the error.
          example: example_value
  responses:
    BadRequestError:
      description: The request is malformed or contains invalid data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFoundError:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnauthorizedError:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for authenticating API requests to the automation controller.
externalDocs:
  description: Ansible Automation Platform API Documentation
  url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html-single/automation_execution_api_overview/index