AAP 2.6 REST API Guide: Automate the Automation Platform
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
Master the AAP 2.6 REST API for programmatic management. Launch jobs, manage inventories, create credentials, query job results, and integrate AAP with CI/CD pipelines, ServiceNow, and custom applications.
AAP 2.6 API Overview
Every action available in the AAP web UI is also available through the REST API. The API enables: • Programmatic job execution — trigger automation from scripts, CI/CD, or external tools • Integration with ITSM platforms — ServiceNow, Jira, PagerDuty • Self-service portals — build custom UIs on top of AAP • Bulk operations — manage hundreds of hosts, credentials, or templates • Monitoring and reporting — extract job data for dashboards
Authentication
Personal Access Tokens (PAT)
The recommended authentication method:
Using Tokens
OAuth2 Application Tokens
For service-to-service integration:
API Endpoints Reference
Core Resources
| Endpoint | Description | |----------|-------------| | /api/controller/v2/ping/ | Health check (no auth required) | | /api/controller/v2/me/ | Current user info | | /api/controller/v2/config/ | Platform configuration | | /api/controller/v2/dashboard/ | Summary statistics |
Automation Resources
| Endpoint | Description | |----------|-------------| | /api/controller/v2/job_templates/ | Job templates CRUD | | /api/controller/v2/workflow_job_templates/ | Workflow templates | | /api/controller/v2/jobs/ | Job history and status | | /api/controller/v2/workflow_jobs/ | Workflow job history | | /api/controller/v2/inventories/ | Inventories | | /api/controller/v2/hosts/ | Hosts | | /api/controller/v2/groups/ | Host groups | | /api/controller/v2/projects/ | SCM projects | | /api/controller/v2/credentials/ | Credentials (metadata only) | | /api/controller/v2/schedules/ | Job schedules | | /api/controller/v2/notification_templates/ | Notifications |
Platform Resources
| Endpoint | Description | |----------|-------------| | /api/controller/v2/organizations/ | Organizations | | /api/controller/v2/teams/ | Teams | | /api/controller/v2/users/ | Users | | /api/controller/v2/roles/ | RBAC roles | | /api/controller/v2/instances/ | Mesh instances | | /api/controller/v2/instance_groups/ | Instance groups | | /api/controller/v2/execution_environments/ | EE images | | /api/controller/v2/activity_stream/ | Audit log |
Common API Operations
Launch a Job Template
Wait for Job Completion
Get Job Output
Create a Host
Search and Filter
Python API Client
Using requests
Using awxkit (Official SDK)
CI/CD Integration Examples
GitHub Actions
GitLab CI
Jenkins Pipeline
ServiceNow Integration
Trigger AAP from ServiceNow Incident
Webhook Receivers
AAP can receive webhooks from GitHub, GitLab, and other systems:
The webhook URL is:
Configure this URL in GitHub repository Settings → Webhooks.
Pagination and Bulk Operations
Handle Paginated Results
FAQ
What is the API rate limit?
AAP does not enforce a hard rate limit by default, but rapid API calls can impact Controller performance. For bulk operations, add small delays between requests. For monitoring, scrape the metrics endpoint instead of polling job status.
Can I use the API to export/import configurations?
Yes. Use the API to export job templates, inventories, credentials (metadata only), and workflows as JSON. The awx-manage export_assets and awx-manage import_assets CLI commands provide bulk export/import functionality.
Is the API backward compatible?
The /api/v2/ endpoint has been stable since Ansible Tower 3.x. AAP 2.6 adds new endpoints under /api/controller/v2/ but maintains backward compatibility. Check the API changelog in the release notes for deprecations.
How do I find the template ID for API calls?
Browse the API in your browser at https://gateway.example.org/api/controller/v2/ — it provides a browsable interface. Or search by name: /api/controller/v2/job_templates/?search=patching.
Can I use GraphQL instead of REST?
No. AAP provides a REST API only. There is no GraphQL endpoint.
Conclusion
The AAP 2.6 REST API transforms the platform from a UI-driven tool into a programmable automation engine. Whether integrating with CI/CD pipelines, ITSM platforms, or building custom self-service portals, the API provides complete programmatic access to every AAP capability.
Related Articles • AAP 2.6 Architecture and Components: Complete Guide • AAP 2.6 RBAC and Gateway API • AAP 2.6 Configuration as Code with ansible.platform • AAP 2.6 Workflow Templates: Advanced Multi-Step Automation Guide • AAP 2.6 Job Templates and Inventories: Complete Configuration Guide
Category: troubleshooting