# Red Hat Ansible Automation Platform

> An enterprise framework for building and operating IT automation at scale, across hybrid
> cloud and edge. AAP is installed and operated by the customer, so its APIs live on the
> customer's own hosts behind the Platform Gateway; only Automation Hub and Automation
> Analytics are additionally offered as Red Hat-hosted services on the Hybrid Cloud Console.

Provenance: generated by the API Evangelist enrichment pipeline on 2026-08-29 from this repo's
harvested artifacts. Red Hat publishes a corporate llms.txt at https://www.redhat.com/llms.txt
(saved verbatim alongside this file); it is company-wide and names AAP in a single line, so
this document exists to give an agent the API-level map that one does not carry.

## APIs and machine-readable contracts

- [Automation Controller API](https://raw.githubusercontent.com/ansible/aap-mcp-server/main/data/controller-schema.json): OpenAPI 3.0.3, 632 operations. Jobs, job templates, workflows, inventories, hosts, projects, credentials, schedules, notifications. Base path /api/controller/v2/ on the customer's install.
- [Automation Hub API](https://console.redhat.com/api/automation-hub/v3/openapi.json): OpenAPI 3.0.3, 786 operations. Collection namespaces, versions, repositories, sync, certification. Live and anonymously readable; the API itself requires a Red Hat account with an AAP entitlement.
- [Event-Driven Ansible API](https://raw.githubusercontent.com/ansible/aap-mcp-server/main/data/eda-openapi.json): OpenAPI 3.0.3, 120 operations. Rulebook activations, event streams, decision environments, audit rules. Base path /api/eda/v1/.
- [Platform Gateway API](https://raw.githubusercontent.com/ansible/aap-mcp-server/main/data/gateway-schema.json): OpenAPI 3.0.3, 206 operations. Users, teams, organizations, role definitions, authenticators, OAuth applications and tokens. Base path /api/gateway/v1/.
- [Ansible Lightspeed API](https://raw.githubusercontent.com/ansible/aap-mcp-server/main/data/lightspeed.json): OpenAPI 3.0.3, 23 operations. Playbook and role generation, explanations, chat, content matches. Base path /api/lightspeed/v1/.

## Agent access

- [AAP MCP Service](https://github.com/ansible/aap-mcp-server): Red Hat's first-party Model Context Protocol server, Apache-2.0. Generates one MCP tool per REST operation across all five services, named {service}.{operationId}. Customer-run — there is no Red Hat-hosted MCP URL. Registers as `claude mcp add aap-mcp -t http http://localhost:3000/mcp -H 'Authorization: Bearer <aap_token>'`.
- Write operations are DISABLED by default (ALLOW_WRITE_OPERATIONS=false), and tool visibility is filtered per user by AAP RBAC.
- Seven curated toolsets are served on their own endpoints: job_management, inventory_management, system_monitoring, user_management, security_compliance, platform_configuration, content_discovery.
- Red Hat gives its shipped MCP Servers a 12-month per-release support lifecycle, independent of the platform lifecycle.

## Authentication

- OAuth 2.0 at the Platform Gateway: /o/authorize/ and /o/token/, authorization_code and password grants, scopes `read` and `write`.
- Bearer personal/application tokens for Automation Controller and Automation Hub; HTTP Basic also accepted.
- Event-Driven Ansible accepts a Gateway-minted JWT in the X-DAB-JW-TOKEN header.
- From AAP 2.5 the Gateway is the single front door for every component.

## Runtime semantics an agent needs

- Pagination: page + page_size on Controller/Gateway/EDA (count/next/previous/results); limit + offset on Automation Hub (meta.count, links.*).
- Filtering: `search` and `order_by` on nearly every Controller collection, plus Django-style field lookups (id__gt, name__icontains).
- Idempotency: NOT supported. There is no Idempotency-Key anywhere in the contract. Re-POSTing a launch starts another job.
- Reversibility: cancel exists and is queryable — GET the cancel endpoint returns {"can_cancel": true|false}. jobs_cancel_create, workflow_jobs_cancel_create, ad_hoc_commands_cancel_create, project_updates_cancel_create, inventory_updates_cancel_create, eda activations_disable_create, hub tasks_cancel. Cancelling stops the run; it does NOT undo changes an already-executed playbook made to managed hosts.
- Dry run: GET controller.job_templates_launch_retrieve returns what a launch would require without launching. Job templates also support job_type "check" (Ansible check mode).
- Errors: plain application/json, not RFC 9457. The Controller and Automation Hub specs declare no 4xx/5xx responses at all.
- Rate limits: none published. The only 429 in the contract is on Ansible Lightspeed ("Request was throttled"), with no headers and no numbers.

## Repository artifacts

- openapi/ — the five harvested specs, verbatim, with provenance in openapi/_sources.yml
- mcp/ — MCP server manifest and a tool crosswalk binding 136 curated tools to their backing operationIds
- authentication/, scopes/ — derived auth profile and OAuth scopes
- conventions/ — pagination, filtering, idempotency, dry-run and reversibility
- errors/ — the error catalog derived from declared 4xx/5xx responses
- lifecycle/ — support phases, deprecation counts, MCP server lifecycle
- data-model/ — the entity graph
- asyncapi/ — inbound webhooks, outbound notifications and the EDA event surface
- packages/, cli/ — first-party libraries and the `awx` command line client
- conformance/, security/ — standards posture, certifications, CSAF/VEX security data

## Human entry points

- [Product](https://www.redhat.com/en/technologies/management/ansible)
- [Documentation](https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/)
- [Life cycle and support policy](https://access.redhat.com/support/policy/updates/ansible-automation-platform)
- [Pricing and deployment options](https://www.redhat.com/en/technologies/management/ansible/pricing)
- [Trial](https://www.redhat.com/en/technologies/management/ansible/trial)
- [GitHub organization](https://github.com/ansible)
- [Status](https://status.redhat.com/)
- [Security](https://www.redhat.com/.well-known/security.txt)