Ansible REST API: Call Web APIs with the uri Module

The ansible.builtin.uri Module

The uri module is Ansible's built-in HTTP client. Use it to interact with REST APIs, web services, and health endpoints directly from your playbooks.

GET Request

- name: Get API data
  ansible.builtin.uri:
    url: https://api.example.com/servers
    method: GET
    return_content: true
  register: api_response

- name: Show response
  ansible.builtin.debug:
    msg: "{{ api_response.json }}"

POST Request

- name: Create a resource
  ansible.builtin.uri:
    url: https://api.example.com/servers
    method: POST
    body:
      name: web-server-01
      type: t3.medium
      region: us-east-1
    body_format: json
    headers:
      Authorization: "Bearer {{ api_token }}"
    status_code: 201
  register: create_result

PUT Request (Update)

- name: Update a resource
  ansible.builtin.uri:
    url: "https://api.example.com/servers/{{ server_id }}"
    method: PUT
    body:
      name: web-server-01-updated
      type: t3.large
    body_format: json
    headers:
      Authorization: "Bearer {{ api_token }}"
      Content-Type: application/json

DELETE Request

- name: Delete a resource
  ansible.builtin.uri:
    url: "https://api.example.com/servers/{{ server_id }}"
    method: DELETE
    headers:
      Authorization: "Bearer {{ api_token }}"
    status_code: [200, 204]

Authentication Methods

Bearer Token

- name: API call with bearer token
  ansible.builtin.uri:
    url: https://api.example.com/data
    headers:
      Authorization: "Bearer {{ vault_api_token }}"
  no_log: true

Basic Auth

- name: API call with basic auth
  ansible.builtin.uri:
    url: https://api.example.com/data
    url_username: "{{ api_user }}"
    url_password: "{{ vault_api_password }}"
    force_basic_auth: true
  no_log: true

API Key Header

- name: API call with API key
  ansible.builtin.uri:
    url: https://api.example.com/data
    headers:
      X-API-Key: "{{ vault_api_key }}"
  no_log: true

Error Handling

- name: Call API with error handling
  ansible.builtin.uri:
    url: https://api.example.com/health
    method: GET
    status_code: [200, 201, 204]
    timeout: 30
  register: health_check
  retries: 3
  delay: 10
  until: health_check.status == 200
  failed_when: health_check.status not in [200, 201]

Parse JSON Response

- name: Get server list
  ansible.builtin.uri:
    url: https://api.example.com/servers
    return_content: true
  register: servers

- name: Show server names
  ansible.builtin.debug:
    msg: "Server: {{ item.name }} ({{ item.status }})"
  loop: "{{ servers.json.results }}"

- name: Get specific field
  ansible.builtin.set_fact:
    server_count: "{{ servers.json.results | length }}"

Download a File

- name: Download file via API
  ansible.builtin.uri:
    url: https://api.example.com/export/report.csv
    dest: /tmp/report.csv
    headers:
      Authorization: "Bearer {{ api_token }}"

For simple file downloads, prefer get_url:

- name: Download with get_url
  ansible.builtin.get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
    checksum: sha256:abc123...

Wait for API to Be Ready

- name: Wait for service to be healthy
  ansible.builtin.uri:
    url: "http://{{ inventory_hostname }}:8080/health"
    method: GET
    status_code: 200
  register: health
  until: health.status == 200
  retries: 30
  delay: 10

Common Parameters Reference

Parameter	Description	Example
`url`	Target URL	`https://api.example.com`
`method`	HTTP method	`GET`, `POST`, `PUT`, `DELETE`, `PATCH`
`body`	Request body	`{"key": "value"}`
`body_format`	Body encoding	`json`, `form-urlencoded`, `raw`
`headers`	HTTP headers	`{"Authorization": "Bearer token"}`
`status_code`	Expected status	`200`, `[200, 201]`
`return_content`	Include body in result	`true`
`timeout`	Request timeout (seconds)	`30`
`validate_certs`	Verify SSL	`true` (default)
`dest`	Save response to file	`/tmp/output.json`

Ansible Tutorial for Beginners — Complete getting started guide
How to Install Ansible — Installation on all platforms
Ansible Training — Courses and certifications
Ansible Dry Run — Test playbooks safely
Ansible Facts — Gather system info
Ansible Vault — Encrypt secrets
Ansible Error Handling — Handle failures

Explore 800+ Ansible tutorials with practical automation examples on AnsibleByExample.