Projects - AWX

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

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

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"
}

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.

Documentation Index

​Overview

​Endpoints

​List Projects

​Create Project

​Retrieve Project

​Response Schema

​Update Project

​Delete Project

​Trigger Project Update

​Copy Project

​List Playbooks

​List Project Inventories

​Project Updates

​List Project Updates

​Get Latest Update

​Project Schedules

​Project Teams

​Notification Templates

​Started Notifications

​Success Notifications

​Error Notifications

​Object Roles

​Activity Stream

​Access List

​SCM Types

​Git

​Subversion

​Archive

​Manual

​Filtering

​Ordering

​Complete Example

​Best Practices

Overview

Endpoints

List Projects

Create Project

Retrieve Project

Response Schema

Update Project

Delete Project

Trigger Project Update

Copy Project

List Playbooks

List Project Inventories

Project Updates

List Project Updates

Get Latest Update

Project Schedules

Project Teams

Notification Templates

Started Notifications

Success Notifications

Error Notifications

Object Roles

Activity Stream

Access List

SCM Types

Git

Subversion

Archive

Manual

Filtering

Ordering

Complete Example

Best Practices