Job Templates

Overview

Job templates define parameters for running Ansible playbooks. They combine a project, playbook, inventory, and credentials into a reusable template that can be launched on-demand or scheduled.

Endpoints

Method	Endpoint	Description
GET	`/api/v2/job_templates/`	List job templates
POST	`/api/v2/job_templates/`	Create job template
GET	`/api/v2/job_templates/{id}/`	Retrieve job template
PATCH	`/api/v2/job_templates/{id}/`	Update job template
DELETE	`/api/v2/job_templates/{id}/`	Delete job template
POST	`/api/v2/job_templates/{id}/launch/`	Launch job
POST	`/api/v2/job_templates/{id}/copy/`	Copy job template

List Job Templates

curl -X GET \
  https://awx.example.com/api/v2/job_templates/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Job Template

curl -X POST \
  https://awx.example.com/api/v2/job_templates/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy Application",
    "description": "Deploy app to production",
    "job_type": "run",
    "inventory": 3,
    "project": 5,
    "playbook": "site.yml",
    "credentials": [7, 8],
    "forks": 5,
    "limit": "",
    "verbosity": 0,
    "extra_vars": "---\nenv: production",
    "job_tags": "",
    "force_handlers": false,
    "skip_tags": "",
    "start_at_task": "",
    "timeout": 0,
    "use_fact_cache": false,
    "allow_simultaneous": false,
    "diff_mode": false
  }'

name

string

required

Job template name

description

string

Job template description

job_type

string

default:"run"

Job type: run or check

inventory

integer

required

Inventory ID

project

integer

required

Project ID

playbook

string

required

Playbook filename from the project

credentials

array

Array of credential IDs

forks

integer

default:"0"

Number of parallel processes (0 = use Ansible default)

limit

string

Host pattern to limit job execution

verbosity

integer

default:"0"

Ansible verbosity: 0-5 (0=normal, 5=connection debug)

extra_vars

string

Extra variables in YAML or JSON

job_tags

string

Comma-separated Ansible tags to run

skip_tags

string

Comma-separated Ansible tags to skip

start_at_task

string

Task name to start at

timeout

integer

default:"0"

Job timeout in seconds (0 = no timeout)

diff_mode

boolean

default:"false"

Show differences when files are changed

allow_simultaneous

boolean

default:"false"

Allow multiple jobs from this template to run simultaneously

use_fact_cache

boolean

default:"false"

Use Ansible fact cache

become_enabled

boolean

default:"false"

Enable privilege escalation

host_config_key

string

Enable provisioning callback with this key

ask_*_on_launch

boolean

Prompt for field at launch:

ask_inventory_on_launch
ask_credential_on_launch
ask_limit_on_launch
ask_tags_on_launch
ask_skip_tags_on_launch
ask_job_type_on_launch
ask_verbosity_on_launch
ask_variables_on_launch
ask_scm_branch_on_launch
ask_diff_mode_on_launch
ask_execution_environment_on_launch
ask_labels_on_launch
ask_forks_on_launch
ask_job_slice_count_on_launch
ask_timeout_on_launch
ask_instance_groups_on_launch

survey_enabled

boolean

default:"false"

Enable survey

webhook_service

string

Enable webhook: github or gitlab

webhook_credential

integer

Webhook credential ID

execution_environment

integer

Execution environment ID

labels

array

Array of label IDs

instance_groups

array

Array of instance group IDs

job_slice_count

integer

default:"1"

Number of job slices for distributed execution

Retrieve Job Template

curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Response includes all fields plus:

status

string

Template status: new, pending, waiting, running, successful, failed, error, canceled, never updated, ok, missing

last_job_run

string

Last job execution timestamp

last_job_failed

boolean

Whether last job failed

next_job_run

string

Next scheduled run

Links to related resources:

organization - Parent organization
inventory - Job inventory
project - Source project
execution_environment - Execution environment
credentials - Attached credentials
labels - Associated labels
jobs - Job history
schedules - Execution schedules
launch - Launch endpoint
webhook_key - Webhook configuration
webhook_receiver - Webhook URL
activity_stream - Activity log
notification_templates_* - Notification templates
survey_spec - Survey specification
access_list - Access list
object_roles - Available roles
instance_groups - Instance groups
slice_workflow_jobs - Slice workflow jobs
copy - Copy endpoint

Update Job Template

curl -X PATCH \
  https://awx.example.com/api/v2/job_templates/10/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "extra_vars": "---\nenv: staging\ndebug: true"
  }'

Delete Job Template

curl -X DELETE \
  https://awx.example.com/api/v2/job_templates/10/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Launch Job

curl -X POST \
  https://awx.example.com/api/v2/job_templates/10/launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": "web01",
    "extra_vars": "deploy_version: v2.0"
  }'

Promptable fields can be overridden at launch if ask_*_on_launch is enabled. Returns a job object with status URL.

Survey Specification

Get Survey

curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/survey_spec/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Create/Update Survey

curl -X POST \
  https://awx.example.com/api/v2/job_templates/10/survey_spec/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deployment Survey",
    "description": "Deployment parameters",
    "spec": [
      {
        "question_name": "Environment",
        "question_description": "Target environment",
        "required": true,
        "type": "multiplechoice",
        "variable": "deploy_env",
        "choices": ["dev", "staging", "production"],
        "default": "staging"
      },
      {
        "question_name": "Version",
        "question_description": "Application version",
        "required": true,
        "type": "text",
        "variable": "app_version",
        "min": 1,
        "max": 20
      }
    ]
  }'

Delete Survey

curl -X DELETE \
  https://awx.example.com/api/v2/job_templates/10/survey_spec/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Jobs

List jobs created from this template:

curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/jobs/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Schedules

curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/schedules/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Labels

curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/labels/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Instance Groups

curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/instance_groups/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Credentials

curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/credentials/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Notifications

# Started notifications
curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/notification_templates_started/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Success notifications
curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/notification_templates_success/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Error notifications
curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/notification_templates_error/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Webhooks

Get Webhook Key

curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/webhook_key/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Regenerate Webhook Key

curl -X POST \
  https://awx.example.com/api/v2/job_templates/10/webhook_key/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Provisioning Callback

Enable callback to allow hosts to trigger their own configuration:

Set host_config_key on the job template
Configure the callback URL on the host

# Callback URL format
curl -X POST \
  "https://awx.example.com/api/v2/job_templates/10/callback/" \
  -d "host_config_key=SECRET_KEY"

Object Roles

curl -X GET \
  https://awx.example.com/api/v2/job_templates/10/object_roles/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Available roles:

admin_role - Full template administration
execute_role - Launch jobs from template
read_role - View template details

Copy Job Template

curl -X POST \
  https://awx.example.com/api/v2/job_templates/10/copy/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy Application Copy"
  }'

Filtering

# By name
?name__icontains=deploy

# By project
?project=5

# By inventory
?inventory=3

# By playbook
?playbook=site.yml

# Failed jobs
?last_job_failed=true

Complete Example

import requests
import json
import time

base_url = "https://awx.example.com/api/v2"
token = "YOUR_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Create job template
template_data = {
    "name": "Deploy Web App",
    "description": "Deploy web application",
    "job_type": "run",
    "inventory": 3,
    "project": 5,
    "playbook": "deploy.yml",
    "credentials": [7],
    "extra_vars": "---\napp_version: latest",
    "ask_limit_on_launch": True,
    "ask_variables_on_launch": True
}

response = requests.post(
    f"{base_url}/job_templates/",
    headers=headers,
    data=json.dumps(template_data)
)

if response.status_code == 201:
    template = response.json()
    template_id = template['id']
    print(f"Created job template {template_id}")
    
    # Launch job
    launch_data = {
        "limit": "web01",
        "extra_vars": "app_version: v2.0.1"
    }
    
    launch_response = requests.post(
        f"{base_url}/job_templates/{template_id}/launch/",
        headers=headers,
        data=json.dumps(launch_data)
    )
    
    if launch_response.status_code in [201, 202]:
        job = launch_response.json()
        job_id = job['id']
        print(f"Launched job {job_id}")
        
        # Monitor job
        while True:
            job_status = requests.get(
                f"{base_url}/jobs/{job_id}/",
                headers=headers
            ).json()
            
            status = job_status['status']
            print(f"Job status: {status}")
            
            if status in ['successful', 'failed', 'error', 'canceled']:
                break
            
            time.sleep(3)
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Getting Started

Core Resources

Job Management

Advanced

Job Templates

Overview

Endpoints

List Job Templates

Create Job Template

Retrieve Job Template

Update Job Template

Delete Job Template

Launch Job

Survey Specification

Get Survey

Create/Update Survey

Delete Survey

Jobs

Schedules

Labels

Instance Groups

Credentials

Notifications

Webhooks

Get Webhook Key

Regenerate Webhook Key

Provisioning Callback

Object Roles

Copy Job Template

Filtering

Complete Example

Build docs developers (and LLMs) love

Getting Started

Core Resources

Job Management

Advanced

​Overview

​Endpoints

​List Job Templates

​Create Job Template

​Retrieve Job Template

​Update Job Template

​Delete Job Template

​Launch Job

​Survey Specification

​Get Survey

​Create/Update Survey

​Delete Survey

​Jobs

​Schedules

​Labels

​Instance Groups

​Credentials

​Notifications

​Webhooks

​Get Webhook Key

​Regenerate Webhook Key

​Provisioning Callback

​Object Roles

​Copy Job Template

​Filtering

​Complete Example

Build docs developers (and LLMs) love

Overview

Endpoints

List Job Templates

Create Job Template

Retrieve Job Template

Update Job Template

Delete Job Template

Launch Job

Survey Specification

Get Survey

Create/Update Survey

Delete Survey

Jobs

Schedules

Labels

Instance Groups

Credentials

Notifications

Webhooks

Get Webhook Key

Regenerate Webhook Key

Provisioning Callback

Object Roles

Copy Job Template

Filtering

Complete Example