Projects

Manage AWX projects via the API

Overview

Projects in AWX represent source control repositories containing Ansible playbooks. They synchronize content from Git, Subversion, or other SCM systems.

Endpoints

Method	Endpoint	Description
GET	/api/v2/projects/	List projects
POST	/api/v2/projects/	Create project
GET	/api/v2/projects/{id}/	Retrieve project
PATCH	/api/v2/projects/{id}/	Update project
DELETE	/api/v2/projects/{id}/	Delete project
POST	/api/v2/projects/{id}/update/	Trigger SCM update
POST	/api/v2/projects/{id}/copy/	Copy project

List Projects

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

Create Project

curl -X POST \
  https://awx.example.com/api/v2/projects/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ansible Playbooks",
    "description": "Main playbook repository",
    "organization": 1,
    "scm_type": "git",
    "scm_url": "https://github.com/ansible/ansible-examples.git",
    "scm_branch": "master",
    "scm_clean": false,
    "scm_delete_on_update": false,
    "credential": null,
    "timeout": 0,
    "scm_track_submodules": false
  }'

name · string · required

Project name (unique within organization)

description · string

Project description

organization · integer · required

Organization ID

scm_type · string · default: ""

Source control type: git, svn, insights, archive, or empty for manual

scm_url · string

SCM repository URL (required if scm_type is set)

scm_branch · string · default: ""

SCM branch, tag, or commit to checkout

scm_refspec · string · default: ""

Git refspec for advanced SCM operations

scm_clean · boolean · default: "false"

Discard local changes before syncing

scm_delete_on_update · boolean · default: "false"

Delete repository on update

scm_track_submodules · boolean · default: "false"

Track Git submodules

credential · integer

SCM credential ID for authentication

timeout · integer · default: "0"

Update timeout in seconds (0 = no timeout)

local_path · string

Local path for manual projects (read-only for SCM projects)

scm_update_on_launch · boolean · default: "false"

Update repository before running jobs

scm_update_cache_timeout · integer · default: "0"

Cache timeout for project updates (seconds)

allow_override · boolean · default: "false"

Allow changing branch per job template

default_environment · integer

Default execution environment ID

Retrieve Project

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

Response Schema

id · integer

Project ID

name · string

Project name

description · string

Project description

scm_type · string

SCM type: git, svn, insights, archive, or empty

scm_url · string

Repository URL

scm_branch · string

Branch/tag/commit

scm_refspec · string

Git refspec

scm_clean · boolean

Whether to discard local changes

scm_delete_on_update · boolean

Whether to delete repo on update

scm_track_submodules · boolean

Whether to track submodules

scm_update_on_launch · boolean

Whether to update before job launch

scm_update_cache_timeout · integer

Update cache timeout

allow_override · boolean

Whether job templates can override branch

timeout · integer

Update timeout

scm_revision · string

Latest SCM revision (read-only)

last_job_run · string

Last update timestamp

last_job_failed · boolean

Whether last update failed

status · string

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

organization · integer

Organization ID

related · object

Links to related resources:

• organization - Parent organization
• credential - SCM credential
• default_environment - Default execution environment
• playbooks - Available playbooks
• inventories - SCM-based inventories
• scm_inventory_sources - Inventory sources using this project
• teams - Teams with access
• project_updates - Update history
• update - Trigger update endpoint
• schedules - Update schedules
• activity_stream - Activity log
• notification_templates_* - Notification templates
• access_list - Access list
• object_roles - Available roles
• copy - Copy endpoint

Update Project

curl -X PATCH \
  https://awx.example.com/api/v2/projects/5/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scm_branch": "develop",
    "scm_update_on_launch": true
  }'

Delete Project

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

Trigger Project Update

Manually sync the project from SCM:

curl -X POST \
  https://awx.example.com/api/v2/projects/5/update/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns a project_update job that you can monitor.

Copy Project

curl -X POST \
  https://awx.example.com/api/v2/projects/5/copy/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ansible Playbooks Copy"
  }'

List Playbooks

Get available playbooks in the project:

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

Returns an array of playbook filenames.

List Project Inventories

Get SCM-based inventories:

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

Project Updates

List Project Updates

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

Get Latest Update

curl -X GET \
  "https://awx.example.com/api/v2/projects/5/project_updates/?order_by=-created&page_size=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Project Schedules

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

Project Teams

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

Notification Templates

Started Notifications

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

Success Notifications

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

Error Notifications

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

Object Roles

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

Available roles:

• admin_role - Full project administration
• use_role - Use project in job templates
• update_role - Trigger project updates
• read_role - View project details

Activity Stream

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

Access List

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

SCM Types

Git

{
  "scm_type": "git",
  "scm_url": "https://github.com/org/repo.git",
  "scm_branch": "main",
  "scm_refspec": "refs/pull/*/head:refs/remotes/origin/pr/*"
}

Subversion

{
  "scm_type": "svn",
  "scm_url": "https://svn.example.com/repo",
  "scm_branch": "trunk"
}

Archive

{
  "scm_type": "archive",
  "scm_url": "https://example.com/playbooks.tar.gz"
}

Manual

{
  "scm_type": "",
  "local_path": "_manual_project_path_"
}

Filtering

# By name
?name__icontains=ansible

# By organization
?organization=1

# By SCM type
?scm_type=git

# By status
?status=successful

# Failed projects
?last_job_failed=true

Ordering

# By name
?order_by=name

# By last update
?order_by=-last_job_run

# By status
?order_by=status

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 project
project_data = {
    "name": "Infrastructure Playbooks",
    "description": "Infrastructure automation",
    "organization": 1,
    "scm_type": "git",
    "scm_url": "https://github.com/example/playbooks.git",
    "scm_branch": "main",
    "scm_update_on_launch": True,
    "scm_clean": True
}

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

if response.status_code == 201:
    project = response.json()
    project_id = project['id']
    print(f"Created project {project_id}")
    
    # Trigger initial sync
    update_response = requests.post(
        f"{base_url}/projects/{project_id}/update/",
        headers=headers
    )
    
    if update_response.status_code in [200, 202]:
        update_job = update_response.json()
        update_id = update_job['id']
        
        # Poll update status
        while True:
            status_response = requests.get(
                f"{base_url}/project_updates/{update_id}/",
                headers=headers
            )
            status = status_response.json()['status']
            
            print(f"Update status: {status}")
            
            if status in ['successful', 'failed', 'error', 'canceled']:
                break
            
            time.sleep(2)
        
        # List playbooks
        playbooks = requests.get(
            f"{base_url}/projects/{project_id}/playbooks/",
            headers=headers
        ).json()
        
        print(f"Available playbooks: {playbooks}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Best Practices

Use SCM Update on Launch

Enable scm_update_on_launch to ensure playbooks are up-to-date before job runs.

Set Update Cache Timeout

Use scm_update_cache_timeout to avoid excessive SCM updates:

{"scm_update_cache_timeout": 300}

Use Branch Override

Enable allow_override to let job templates specify different branches.

Secure Credentials

Use SCM credentials for private repositories:

{"credential": 5}

Monitor Update Jobs

Always monitor project_update jobs to catch sync failures early.