### Example Time Zones

Source: https://github.com/ansible-community/ara/blob/master/doc/source/api-configuration.md

Examples of valid time zone strings that can be used for the TIME_ZONE setting.

```text
UTC
US/Eastern
America/Montreal
Europe/Paris
```

--------------------------------

### Example of Token-Efficient Failure Report

Source: https://github.com/ansible-community/ara/blob/master/contrib/mcp/reviews/2025-02-11/qwen-coder-next-80b.md

This example demonstrates the concise, structured text output for a playbook failure, contrasting with raw console output. It highlights key information like task, host, error, and code context.

```text
--- Failure 1: Result #995551 ---
Task: Install packages
Action: apt
Host: web-01 (http://.../hosts/42.html)
Error: Package nginx is not available
Code (/etc/ansible/roles/web/tasks/main.yml, line 23):
   >>> 23 | - name: Install packages
       24 |   apt:
       25 |     name: ["nginx={{ web_server_version }}"]
```

--------------------------------

### Start ARA API Server with Podman

Source: https://github.com/ansible-community/ara/blob/master/README.md

Starts an ARA API server using a Podman container, mapping a local directory for settings and the SQLite database, and exposing the API on port 8000.

```bash
# or with podman from the image on quay.io:
podman run --name ara-api --detach --tty \
  --volume ~/.ara/server:/opt/ara -p 8000:8000 \
  quay.io/recordsansible/ara-api:latest
```

--------------------------------

### Start ARA API Server with Docker

Source: https://github.com/ansible-community/ara/blob/master/README.md

Starts an ARA API server using a Docker container, mapping a local directory for settings and the SQLite database, and exposing the API on port 8000.

```bash
# Create a directory for a volume to store settings and a sqlite database
mkdir -p ~/.ara/server

# Start an API server with docker from the image on DockerHub:
docker run --name ara-api --detach --tty \
  --volume ~/.ara/server:/opt/ara -p 8000:8000 \
  docker.io/recordsansible/ara-api:latest
```

--------------------------------

### Install and Configure ARA for Local SQLite

Source: https://github.com/ansible-community/ara/blob/master/README.md

Installs Ansible with ARA, configures Ansible to use ARA callback plugins, and demonstrates running a playbook. Includes commands to list playbooks and hosts via the ARA CLI.

```bash
# Install ansible (or ansible-core) with ara (including API server dependencies)
python3 -m pip install --user ansible "ara[server]"

# Configure Ansible to enable ara
export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"

# Run an Ansible playbook as usual
ansible-playbook playbook.yml

# Check out the CLI
ara playbook list
ara host list

# or the UI at http://127.0.0.1:8000
ara-manage runserver
```

--------------------------------

### Clone ARA Repository and Install Dependencies

Source: https://github.com/ansible-community/ara/blob/master/contrib/mcp/README.rst

Clone the ARA repository and set up a virtual environment to install the necessary Python packages for the MCP server.

```bash
git clone https://codeberg.org/ansible-community/ara ~/.ara/git/ara
cd ~/.ara/git/ara

python3 -m venv .venv
.venv/bin/pip install httpx mcp
```

--------------------------------

### Run ARA API container with Podman

Source: https://github.com/ansible-community/ara/blob/master/doc/source/container-images.md

Start the ARA API container, creating a persistent volume for settings and logs, and mapping the API port.

```bash
mkdir -p ~/.ara/server
podman run --name ara-api --detach --tty \
     --volume ~/.ara/server:/opt/ara:z -p 8000:8000 \
     localhost/ara-api
```

--------------------------------

### Get Ara Plugin Paths

Source: https://github.com/ansible-community/ara/blob/master/doc/source/ansible-configuration.md

Use these commands to find the installation paths for Ara plugins. Export these paths as environment variables to enable Ansible to find them.

```bash
$ python3 -m ara.setup.path
/usr/lib/python3.7/site-packages/ara
```

```bash
$ python3 -m ara.setup.plugins
/usr/lib/python3.7/site-packages/ara/plugins
```

```bash
$ python3 -m ara.setup.action_plugins
/usr/lib/python3.7/site-packages/ara/plugins/action
$ export ANSIBLE_ACTION_PLUGINS=$(python3 -m ara.setup.action_plugins)
```

```bash
$ python3 -m ara.setup.callback_plugins
/usr/lib/python3.7/site-packages/ara/plugins/callback
$ export ANSIBLE_CALLBACK_PLUGINS=$(python3 -m ara.setup.callback_plugins)
```

```bash
$ python3 -m ara.setup.lookup_plugins
/usr/lib/python3.7/site-packages/ara/plugins/lookup
$ export ANSIBLE_LOOKUP_PLUGINS=$(python3 -m ara.setup.lookup_plugins)
```

--------------------------------

### Example File Hierarchy for Distributed SQLite

Source: https://github.com/ansible-community/ara/blob/master/doc/source/distributed-sqlite-backend.md

Illustrates a potential file structure for storing multiple SQLite databases, each accessible via a unique URL path. This structure helps in organizing databases for different CI jobs or environments.

```text
/var/www/logs/
├── 1
│   ├── ara-report
│   │   └── ansible.sqlite
│   └── console.txt
├── 2
│   ├── logs.tar.gz
│   └── some
│       └── path
│           └── ara-report
│               └── ansible.sqlite
└── 3
    ├── builds.txt
    ├── dev
    │   └── ara-report
    │       └── ansible.sqlite
    └── prod
        └── ara-report
            └── ansible.sqlite
```

--------------------------------

### Run ARA API Container with podman

Source: https://github.com/ansible-community/ara/blob/master/contrib/container-images/README.rst

Start the ARA API container using podman, mapping a local directory for persistent storage and exposing the API port.

```bash
$ mkdir -p ~/.ara/server
$ podman run --name ara-api --detach --tty \
     --volume ~/.ara/server:/opt/ara:z -p 8000:8000 \
     localhost/ara-api
bc4b7630c265bdac161f2e08116f3f45c2db519fb757ddf865bb0f212780fa8d
```

--------------------------------

### Troubleshoot Playbook Failures

Source: https://github.com/ansible-community/ara/blob/master/contrib/mcp/AGENTS.md

Use `troubleshoot_playbook` to aggregate all failures, error messages, source code context, and relevant host facts for a failed playbook. This is the recommended starting point for debugging.

```python
troubleshoot_playbook(id=<playbook_id>)
```

--------------------------------

### List Playbooks by Path and Order by Duration

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Get a list of playbooks matching a partial path and order the results by duration. Uses the default offline API client.

```bash
ara playbook list --path="playbooks/site.yaml" --order=duration
```

--------------------------------

### Set up ARA Callback and Send Data to API Server

Source: https://github.com/ansible-community/ara/blob/master/contrib/container-images/README.rst

This sequence of commands sets up a Python virtual environment, installs Ansible and ARA, configures Ansible to use the ARA callback plugin, and sets the API server endpoint. It concludes by running an Ansible playbook, which will send data to the configured ARA API server.

```bash
# Create and source a python3 virtual environment
python3 -m venv ~/.ara/virtualenv
source ~/.ara/virtualenv/bin/activate

# Install Ansible and ARA
pip3 install ansible ara

# Configure Ansible to know where ARA's callback plugin is located
export ANSIBLE_CALLBACK_PLUGINS=$(python3 -m ara.setup.callback_plugins)

# Set up the ARA callback to know where the API server is
export ARA_API_CLIENT=http
export ARA_API_SERVER="http://127.0.0.1:8000"

# Run any of your Ansible playbooks as you normally would
ansible-playbook playbook.yml
```

--------------------------------

### Run Development Server with ara-manage

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Start the embedded development server using `ara-manage runserver`. This is suitable for small-scale usage. For production, deploy with a WSGI server and web server. Options include controlling threading, reloading, and static file serving.

```bash
$ ara-manage runserver --help
[ara] Using settings file: /root/.ara/server/settings.yaml
usage: ara-manage runserver [-h] [--ipv6] [--nothreading] [--noreload]
                            [--nostatic] [--insecure] [--version]
                            [--settings SETTINGS] [--pythonpath PYTHONPATH]
                            [--no-color] [--force-color] [--skip-checks]
                            [addrport]

Starts a lightweight web server for development and also serves static files.

positional arguments:
  addrport              Optional port number, or ipaddr:port

options:
  -h, --help            show this help message and exit
  --ipv6, -6            Tells Django to use an IPv6 address.
  --nothreading         Tells Django to NOT use threading.
  --noreload            Tells Django to NOT use the auto-reloader.
  --nostatic            Tells Django to NOT automatically serve static files
                        at STATIC_URL.
  --insecure            Allows serving static files even if DEBUG is False.
  --version             Show program's version number and exit.
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.

```

--------------------------------

### Get File Content

Source: https://github.com/ansible-community/ara/blob/master/contrib/mcp/TODO.md

Fetches the content of a specific file for a given playbook run, identified by playbook ID and file reference.

```bash
get files/<A_id>
```

```bash
get files/<B_id>
```

--------------------------------

### Example Report Grouping

Source: https://github.com/ansible-community/ara/blob/master/contrib/mcp/TODO.md

Illustrates how changed results are grouped by host and classification, differentiating between real and possibly spurious changes. This format helps in quickly identifying the impact of playbook runs.

```text
Host: web-01
  Real changes (7):
    - Installed nginx 1.24.0 (apt)
    - Created /etc/nginx/sites-available/app.conf (template)
    - Enabled and started nginx (systemd)
    ...
  Possibly spurious (2):
    - "Run database migration" (shell) — changed_when not set
    - "Check connectivity" (command) — changed_when not set

Host: web-02
  ...

```

--------------------------------

### Troubleshoot Host Issues

Source: https://github.com/ansible-community/ara/blob/master/contrib/mcp/AGENTS.md

Use `troubleshoot_host` to get a host-centric view of failures across multiple runs. This helps identify if a specific host consistently experiences problems.

```python
troubleshoot_host(id=<host_id>)
```

--------------------------------

### Run ARA Integration Tests Locally

Source: https://github.com/ansible-community/ara/blob/master/doc/source/contributing.md

This command sequence allows you to run integration tests locally. It activates a tox virtual environment, sets necessary environment variables for ARA plugins, and then executes a sample playbook. Finally, it starts the ARA development server.

```bash
tox -e ansible-integration --notest
source .tox/ansible-integration/bin/activate
export ANSIBLE_CALLBACK_PLUGINS=$(python3 -m ara.setup.callback_plugins)
export ANSIBLE_ACTION_PLUGINS=$(python3 -m ara.setup.action_plugins)
export ANSIBLE_LOOKUP_PLUGINS=$(python3 -m ara.setup.lookup_plugins)
ansible-playbook tests/integration/smoke.yaml
ara-manage runserver
# Browse to http://127.0.0.1:8000
```

--------------------------------

### Build and Update Fedora Package

Source: https://github.com/ansible-community/ara/blob/master/doc/source/distribution-packages.md

Commands to build the package for rawhide and stable releases, and to open a Bodhi update for stable releases. This is part of the process to get new versions into Fedora repositories.

```bash
# First, check out the desired branch and then `fedpkg build`.

# For rawhide, a successful build will automatically end up in repositories.
# For stable releases we must open a bodhi update with `fedpkg update`.

```

--------------------------------

### Nginx Configuration for ARA Proxy

Source: https://github.com/ansible-community/ara/blob/master/doc/source/api-security.md

This is a placeholder for an Nginx configuration example. The actual configuration would typically involve setting up a reverse proxy to the ARA API server and potentially handling authentication.

```nginx
# /etc/nginx/conf.d/ara.conf

```

--------------------------------

### Configure ara_default callback plugin (offline recording)

Source: https://context7.com/ansible-community/ara/llms.txt

Minimal ansible.cfg configuration for offline recording using SQLite. Ensure callback, action, and lookup plugins are correctly pointed to ARA's setup scripts.

```ini
# ansible.cfg — minimal configuration for offline recording (SQLite, no server needed)
[defaults]
callback_plugins = $(python3 -m ara.setup.callback_plugins)
action_plugins   = $(python3 -m ara.setup.action_plugins)
lookup_plugins   = $(python3 -m ara.setup.lookup_plugins)

[ara]
api_client = offline
```

--------------------------------

### Run SQL Migrations Manually

Source: https://github.com/ansible-community/ara/blob/master/doc/source/troubleshooting.md

Execute this command to manually run SQL migrations if you encounter database exceptions before the callback plugin has created the necessary tables. This is typically needed when starting the server or running CLI commands before migrations have been applied.

```bash
ara-manage migrate
```

--------------------------------

### Run SQL Migrations with ara-manage

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Use `ara-manage migrate` to update the database schema. This command is essential before starting the API server. It supports various options for controlling the migration process, such as `--noinput` to prevent prompts and `--plan` to preview actions.

```bash
$ ara-manage migrate --help
[ara] Using settings file: /root/.ara/server/settings.yaml
usage: ara-manage migrate [-h] [--noinput] [--database {default}] [--fake]
                          [--fake-initial] [--plan] [--run-syncdb] [--check]
                          [--prune] [--version] [-v {0,1,2,3}]
                          [--settings SETTINGS] [--pythonpath PYTHONPATH]
                          [--traceback] [--no-color] [--force-color]
                          [--skip-checks]
                          [app_label] [migration_name]

Updates database schema. Manages both apps with migrations and those without.

positional arguments:
  app_label             App label of an application to synchronize the state.
  migration_name        Database state will be brought to the state after that
                        migration. Use the name "zero" to unapply all
                        migrations.

options:
  -h, --help            show this help message and exit
  --noinput, --no-input
                        Tells Django to NOT prompt the user for input of any
                        kind.
  --database {default}  Nominates a database to synchronize. Defaults to the
                        "default" database.
  --fake                Mark migrations as run without actually running them.
  --fake-initial        Detect if tables already exist and fake-apply initial
                        migrations if so. Make sure that the current database
                        schema matches your initial migration before using
                        this flag. Django will only check for an existing
                        table name.
  --plan                Shows a list of the migration actions that will be
                        performed.
  --run-syncdb          Creates tables for apps without migrations.
  --check               Exits with a non-zero status if unapplied migrations
                        exist and does not actually apply migrations.
  --prune               Delete nonexistent migrations from the
                        django_migrations table.
  --version             Show program's version number and exit.
  -v, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Display a full stack trace on CommandError exceptions.
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.

```

--------------------------------

### Get Ara Plugin Paths in Python

Source: https://github.com/ansible-community/ara/blob/master/doc/source/ansible-configuration.md

Access Ara plugin installation paths directly within Python scripts using these helper modules.

```python
>>> from ara.setup import callback_plugins
>>> print(callback_plugins)
/usr/lib/python3.7/site-packages/ara/plugins/callback
```

```python
>>> from ara.setup import action_plugins
>>> print(action_plugins)
/usr/lib/python3.7/site-packages/ara/plugins/action
```

```python
>>> from ara.setup import lookup_plugins
>>> print(lookup_plugins)
/usr/lib/python3.7/site-packages/ara/plugins/lookup
```

--------------------------------

### Display Help for `ara-manage generate`

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Shows the available options and arguments for the `ara-manage generate` command. This is useful for understanding how to configure the static site generation process.

```text
$ ara-manage generate --help
[ara] Using settings file: /root/.ara/server/settings.yaml
usage: ara-manage generate [-h] [--version] [-v {0,1,2,3}]
                           [--settings SETTINGS] [--pythonpath PYTHONPATH]
                           [--traceback] [--no-color] [--force-color]
                           [--skip-checks]
                           path

Generates a static tree of the web application

positional arguments:
  path                  Path where the static files will be built in

options:
  -h, --help            show this help message and exit
  --version             Show program's version number and exit.
  -v, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Display a full stack trace on CommandError exceptions.
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.
```

--------------------------------

### Configure Database Options with SSL

Source: https://github.com/ansible-community/ara/blob/master/doc/source/api-configuration.md

Set database options, including SSL configuration, using environment variables or a YAML configuration file.

```default
export ARA_DATABASE_OPTIONS='@json {"ssl": {"ca": "/etc/ssl/certificate.pem"}}'
```

```yaml
DATABASE_OPTIONS:
  ssl:
    ca: "/etc/ssl/certificate.pem"
```

--------------------------------

### Show ara-manage createsuperuser Help

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Displays the help message for the `createsuperuser` command, outlining available options for creating superusers.

```text
$ ara-manage createsuperuser --help
[ara] Using settings file: /root/.ara/server/settings.yaml
usage: ara-manage createsuperuser [-h] [--username USERNAME] [--noinput]
                                  [--database {default}] [--email EMAIL]
                                  [--version] [-v {0,1,2,3}]
                                  [--settings SETTINGS]
                                  [--pythonpath PYTHONPATH] [--traceback]
                                  [--no-color] [--force-color] [--skip-checks]

Used to create a superuser.

options:
  -h, --help            show this help message and exit
  --username USERNAME   Specifies the login for the superuser.
  --noinput, --no-input
                        Tells Django to NOT prompt the user for input of any
                        kind. You must use --username with --noinput, along
                        with an option for any other required field.
                        Superusers created with --noinput will not be able to
                        log in until they're given a valid password.
  --database {default}  Specifies the database to use. Default is "default".
  --email EMAIL         Specifies the email for the superuser.
  --version             Show program's version number and exit.
  -v, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Display a full stack trace on CommandError exceptions.
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.
```

--------------------------------

### GET /api/v1/labels

Source: https://context7.com/ansible-community/ara/llms.txt

Lists and manages labels, which are reusable string tags attached to playbooks.

```APIDOC
## GET /api/v1/labels — List and manage labels

### Description
Labels are reusable string tags attached to playbooks for grouping and correlation.

### Method
GET

### Endpoint
/api/v1/labels

### Parameters
(No specific query parameters are detailed in the source for listing labels.)

### Request Example
```bash
# Example command to list labels (assuming endpoint exists)
curl -s http://localhost:8000/api/v1/labels
```

### Response
#### Success Response (200)
(The structure of the response for labels is not detailed in the source.)
```

--------------------------------

### GET /api/v1/tasks

Source: https://context7.com/ansible-community/ara/llms.txt

Lists tasks across all playbooks, with support for filtering by various attributes.

```APIDOC
## GET /api/v1/tasks — List tasks with filtering

### Description
Returns tasks across all playbooks. Supports filtering by action/module name, name, path, status, handler flag, and counts of warnings, deprecations, and exceptions.

### Method
GET

### Endpoint
/api/v1/tasks

### Parameters
#### Query Parameters
- **playbook** (integer) - Optional - Filter by playbook ID.
- **status** (string) - Optional - Filter by task status.
- **action** (string) - Optional - Filter by task action or module name.
- **name** (string) - Optional - Filter by task name.
- **path** (string) - Optional - Filter by the path of the task file.
- **exceptions_count__gt** (integer) - Optional - Filter for tasks with more than the specified number of exceptions.
- **handler** (boolean) - Optional - Filter for handler tasks.

### Request Example
```bash
curl -s "http://localhost:8000/api/v1/tasks?playbook=5&status=failed"
```

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the task.
- **name** (string) - The name of the task.
- **action** (string) - The action or module used by the task.
- **path** (string) - The path to the file where the task is defined.
- **lineno** (integer) - The line number of the task in its file.
- **playbook** (object) - Information about the playbook the task belongs to.
- **status** (string) - The status of the task execution.
- **handler** (boolean) - Indicates if the task is a handler.
- **warnings_count** (integer) - Number of warnings generated by the task.
- **deprecations_count** (integer) - Number of deprecations noted for the task.
- **exceptions_count** (integer) - Number of exceptions encountered during the task.

#### Response Example
(Response structure for tasks is not explicitly detailed in the source, but would typically include fields like id, name, action, status, etc.)
```

--------------------------------

### GET /api/v1/latesthosts

Source: https://context7.com/ansible-community/ara/llms.txt

Retrieves the latest playbook result for each unique host, useful for dashboards.

```APIDOC
## GET /api/v1/latesthosts — Latest playbook result per host

### Description
Read-only endpoint that returns one entry per unique hostname, pointing to that host's most recent playbook run. Useful for dashboards showing current host state.

### Method
GET

### Endpoint
/api/v1/latesthosts

### Parameters
#### Query Parameters
- **failed__gt** (integer) - Optional - Filter for hosts with more than the specified number of failures in their latest run.

### Request Example
```bash
curl -s http://localhost:8000/api/v1/latesthosts
```

### Response
#### Success Response (200)
- **results** (array) - A list of host objects with their latest playbook run information.
  - **name** (string) - The name of the host.
  - **host** (object) - Details of the host's latest playbook run.
    - **id** (integer) - Unique identifier for the host.
    - **name** (string) - The name of the host.
    - **changed** (integer) - Count of tasks that reported changes.
    - **failed** (integer) - Count of failed tasks.
    - **ok** (integer) - Count of successful tasks.
    - **skipped** (integer) - Count of skipped tasks.
    - **unreachable** (integer) - Count of unreachable hosts.
    - **playbook** (object) - Information about the latest playbook run.

#### Response Example
```json
{
  "results": [
    {
      "name": "web01.example.org",
      "host": {
        "id": 88,
        "name": "web01.example.org",
        "changed": 1,
        "failed": 0,
        "ok": 30,
        "skipped": 2,
        "unreachable": 0,
        "playbook": {"id": 99, "name": "Deploy web app", "status": "completed"}
      }
    }
  ]
}
```
```

--------------------------------

### Show Help for `ara playbook prune`

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Displays the help message for the `ara playbook prune` command, outlining all available options and their descriptions. This command requires write privileges.

```text
$ ara playbook prune --help
```

--------------------------------

### Display Help for 'ara play list'

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Shows all available options and arguments for the 'ara play list' command. Use this to understand the full range of filtering and output customization.

```text
$ ara play list --help
```

--------------------------------

### GET /api/v1/files

Source: https://context7.com/ansible-community/ara/llms.txt

Lists Ansible files recorded during playbook execution, with filtering and detail retrieval.

```APIDOC
## GET /api/v1/files — List playbook files

### Description
Returns Ansible files (playbooks, task files, var files, role files) recorded during playbook execution.

### Method
GET

### Endpoint
/api/v1/files

### Parameters
#### Query Parameters
- **playbook** (integer) - Optional - Filter files by playbook ID.
- **path** (string) - Optional - Filter files by path.

### Request Example
```bash
curl -s "http://localhost:8000/api/v1/files?playbook=5"
```

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the file.
- **path** (string) - The path of the file.
- **type** (string) - The type of the file (e.g., playbook, tasks, vars).
- **playbook** (integer) - The ID of the playbook this file is associated with.
- **content** (string) - The content of the file (decompressed if applicable).

#### Response Example
(Response structure for files is not explicitly detailed in the source, but would typically include fields like id, path, type, playbook, etc.)

### Detailed File Retrieval
#### GET /api/v1/files/{id}

### Description
Retrieves detailed information for a specific file by its ID.

### Method
GET

### Endpoint
/api/v1/files/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the file to retrieve.

### Request Example
```bash
curl -s http://localhost:8000/api/v1/files/22
```
```

--------------------------------

### GET /api/v1/records

Source: https://context7.com/ansible-community/ara/llms.txt

Retrieves custom key/value records stored by the `ara_record` module, filterable by playbook and key.

```APIDOC
## GET /api/v1/records — Retrieve key/value records

### Description
Returns custom key/value data stored by the `ara_record` Ansible module during a playbook run. Filterable by playbook and exact key name.

### Method
GET

### Endpoint
/api/v1/records

### Parameters
#### Query Parameters
- **playbook** (integer) - Optional - Filter records by playbook ID.
- **key** (string) - Optional - Filter records by exact key name.

### Request Example
```bash
curl -s "http://localhost:8000/api/v1/records?playbook=5"
```

### Response
#### Success Response (200)
- **results** (array) - A list of record objects.
  - **id** (integer) - Unique identifier for the record.
  - **key** (string) - The key of the record.
  - **value** (string) - The value of the record.
  - **type** (string) - The data type of the value.
  - **playbook** (integer) - The ID of the playbook this record belongs to.
  - **created** (string) - Timestamp when the record was created.
  - **updated** (string) - Timestamp when the record was last updated.

#### Response Example
```json
{
  "results": [
    {
      "id": 3,
      "key": "git_version",
      "value": "a3f91bc",
      "type": "text",
      "playbook": 5,
      "created": "2025-11-28T09:00:15Z",
      "updated": "2025-11-28T09:00:15Z"
    }
  ]
}
```
```

--------------------------------

### ARA HTTP Client Operations

Source: https://context7.com/ansible-community/ara/llms.txt

Examples of using the ARA HTTP client to perform standard API operations.

```APIDOC
## ARA HTTP Client

### Description
The ARA HTTP client allows direct interaction with the ARA API. It supports mutual TLS for secure connections and custom CA verification.

### Initialization
```python
client = get_client(
    client="http",
    endpoint="https://ara.internal",
    cert="/etc/ara/client.crt",
    key="/etc/ara/client.key",
    verify="/etc/ara/ca-bundle.crt",
)
```

### Operations
Standard API operations work identically on the client.

#### Get Playbooks
```python
playbooks = client.get("/api/v1/playbooks", status="completed")
```

#### Update Playbook Labels
```python
client.patch("/api/v1/playbooks/5", labels=["validated"])
```

#### Delete Playbook
```python
client.delete("/api/v1/playbooks/1")
```
```

--------------------------------

### GET /api/v1/hosts

Source: https://context7.com/ansible-community/ara/llms.txt

Lists hosts with cumulative task result statistics per playbook run, supporting filtering.

```APIDOC
## GET /api/v1/hosts — List hosts with task result statistics

### Description
Returns hosts with cumulative task result counts (ok, changed, failed, skipped, unreachable) per playbook run. Supports filtering by name, playbook, and numeric comparisons.

### Method
GET

### Endpoint
/api/v1/hosts

### Parameters
#### Query Parameters
- **name** (string) - Optional - Filter by host name.
- **playbook** (integer) - Optional - Filter by playbook ID.
- **failed__gt** (integer) - Optional - Filter for hosts with more than the specified number of failures.
- **changed__gt** (integer) - Optional - Filter for hosts with more than the specified number of changes.

### Request Example
```bash
curl -s "http://localhost:8000/api/v1/hosts?failed__gt=0"
```

### Response
#### Success Response (200)
- **results** (array) - A list of host objects.
  - **id** (integer) - Unique identifier for the host.
  - **name** (string) - The name of the host.
  - **playbook** (object) - Information about the playbook.
  - **changed** (integer) - Count of tasks that reported changes.
  - **failed** (integer) - Count of failed tasks.
  - **ok** (integer) - Count of successful tasks.
  - **skipped** (integer) - Count of skipped tasks.
  - **unreachable** (integer) - Count of unreachable hosts.
  - **updated** (string) - Timestamp of the last update.

#### Response Example
```json
{
  "results": [
    {
      "id": 12,
      "name": "web01.example.org",
      "playbook": {"id": 5},
      "changed": 3,
      "failed": 1,
      "ok": 24,
      "skipped": 5,
      "unreachable": 0,
      "updated": "2025-11-28T09:04:10Z"
    }
  ]
}
```
```

--------------------------------

### GET /api/v1/results

Source: https://context7.com/ansible-community/ara/llms.txt

Lists individual task results, supporting filtering by various criteria such as playbook, host, status, and more.

```APIDOC
## GET /api/v1/results — List task results with filtering

### Description
Returns individual task results (one per host per task). Supports filtering by playbook, play, task, host, status (`ok`, `failed`, `skipped`, `unreachable`), `changed`, and `ignore_errors`.

### Method
GET

### Endpoint
/api/v1/results

### Parameters
#### Query Parameters
- **playbook** (integer) - Optional - Filter by playbook ID.
- **play** (integer) - Optional - Filter by play ID.
- **task** (integer) - Optional - Filter by task ID.
- **host** (integer) - Optional - Filter by host ID.
- **status** (string) - Optional - Filter by task status (e.g., `ok`, `failed`, `skipped`, `unreachable`).
- **changed** (boolean) - Optional - Filter for tasks that reported changes.
- **ignore_errors** (boolean) - Optional - Filter for tasks where errors were ignored.

### Request Example
```bash
curl -s "http://localhost:8000/api/v1/results?playbook=5&status=failed"
```

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the result.
- **status** (string) - The status of the task execution.
- **changed** (boolean) - Indicates if the task reported changes.
- **ignore_errors** (boolean) - Indicates if errors were ignored for this task.
- **playbook** (object) - Information about the playbook.
- **play** (object) - Information about the play.
- **task** (object) - Information about the task.
- **host** (object) - Information about the host.
- **content** (object) - Detailed content or output of the task.
- **started** (string) - Timestamp when the task started.
- **duration** (string) - Duration of the task execution.

#### Response Example
```json
{
  "id": 234,
  "status": "failed",
  "changed": false,
  "ignore_errors": false,
  "playbook": {"id": 5, "name": "Provision infra"},
  "play": {"id": 11, "name": "Install packages"},
  "task": {"id": 55, "name": "Install nginx", "action": "ansible.builtin.package", "lineno": 12},
  "host": {"id": 12, "name": "web01.example.org"},
  "content": {"msg": "No package nginx found", "rc": 1},
  "started": "2025-11-28T09:02:10Z",
  "duration": "0:00:05"
}
```
```

--------------------------------

### Show playbook details in YAML format (local)

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Retrieves playbook details using the default offline client and formats the output as YAML.

```bash
ara playbook show 1 -f yaml
```

--------------------------------

### Initialize Bootstrap Tooltips

Source: https://github.com/ansible-community/ara/blob/master/ara/ui/templates/partials/tooltips.html

Selects all elements with the 'data-bs-toggle="tooltip"' attribute and initializes them as Bootstrap tooltips. Ensure Bootstrap JavaScript is loaded.

```javascript
const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))
```

--------------------------------

### Get Playbook Metrics with Limit

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Retrieve playbook metrics, specifying a limit for the number of playbooks to consider. Useful for analyzing a larger historical dataset.

```bash
ara playbook metrics --limit 10000
```

--------------------------------

### List Files for a Playbook

Source: https://github.com/ansible-community/ara/blob/master/contrib/mcp/TODO.md

Fetches all files associated with a specific playbook ID, including their paths and SHA1 hashes.

```bash
list files, playbook=<A_id>
```

```bash
list files, playbook=<B_id>
```

--------------------------------

### Get Task Metrics with Custom Limit

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Use the --limit option to retrieve more than the default 1000 task metrics. This is useful for analyzing larger datasets.

```bash
ara task metrics --limit 10000
```

--------------------------------

### Configure Ansible with Ara Plugin Paths

Source: https://github.com/ansible-community/ara/blob/master/doc/source/ansible-configuration.md

This command outputs an Ansible configuration snippet with Ara plugin paths. You can use this to directly configure your Ansible setup.

```ini
$ python3 -m ara.setup.ansible
[defaults]
callback_plugins=/usr/lib/python3.7/site-packages/ara/plugins/callback
action_plugins=/usr/lib/python3.7/site-packages/ara/plugins/action
lookup_plugins=/usr/lib/python3.7/site-packages/ara/plugins/lookup
```

--------------------------------

### Configure Database Name

Source: https://github.com/ansible-community/ara/blob/master/doc/source/api-configuration.md

Set the name of the database. For SQLite, this is the file path; for other databases, it's the database name.

```text
~/.ara/server/ansible.sqlite
```

--------------------------------

### Filter Task Metrics by Task Path

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Get metrics for tasks that match a specified file path, either fully or partially, using the --path option.

```bash
ara task metrics --path ansible-role-foo
```

--------------------------------

### Show playbook details in JSON format

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Displays detailed playbook information formatted as JSON. Connects to a remote API server.

```bash
ara playbook show --client http --server https://demo.recordsansible.org 1 -f json
```

--------------------------------

### List tasks with filtering

Source: https://context7.com/ansible-community/ara/llms.txt

Retrieve tasks across all playbooks, with filters for action, name, path, status, handler flag, and counts of warnings, deprecations, and exceptions.

```bash
# All failed tasks for a playbook
curl -s "http://localhost:8000/api/v1/tasks?playbook=5&status=failed" | python3 -m json.tool
```

```bash
# Tasks using a specific module
curl -s "http://localhost:8000/api/v1/tasks?action=ansible.builtin.package" | python3 -m json.tool
```

```bash
# Tasks with at least one exception logged
curl -s "http://localhost:8000/api/v1/tasks?exceptions_count__gt=0" | python3 -m json.tool
```

```bash
# Handler tasks only
curl -s "http://localhost:8000/api/v1/tasks?handler=true" | python3 -m json.tool
```

--------------------------------

### Get Host Information

Source: https://github.com/ansible-community/ara/blob/master/contrib/mcp/AGENTS.md

Use `get_host` to retrieve detailed information about a specific host, including Ansible facts. This is useful for diagnosing issues related to host configuration or environment.

```python
get_host(id=<host_id>)
```

--------------------------------

### Print Empty Table for Host Metrics

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Use the --print-empty flag to display a table even when no host metrics data is available.

```bash
--print-empty         Print empty table if there is no data to show.
```

--------------------------------

### Return Host Metrics by Playbook

Source: https://github.com/ansible-community/ara/blob/master/doc/source/cli.md

Retrieve metrics for hosts involved in a specific playbook using the --playbook option.

```bash
ara host metrics --playbook 9001
```