### Install pyfortianalyzer

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/index.md

Install the pyfortianalyzer library using pip. Ensure you are using Python 3.8 or newer.

```bash
pip install pyfortianalyzer
```

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

### Example: Custom Endpoint using FortiAnalyzer POST

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/fortianalyzer-base.md

This example demonstrates how a subclass can extend the `FortiAnalyzer` class to create a custom endpoint method (`get_info`) that utilizes the `post` method to fetch data from a specific FortiAnalyzer URL.

```python
# Used internally by subclasses
from pyfortianalyzer.core.fortianalyzer import FortiAnalyzer

class CustomEndpoint(FortiAnalyzer):
    def get_info(self):
        params = {
            "url": "/some/endpoint",
            "option": ["get", "meta"]
        }
        return self.post(method="get", params=params)
```

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

### Minimal pyfortianalyzer API Example

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/getting-started.md

Initialize the API client and fetch all FortiGates. Ensure you replace placeholder values for host and token.

```python
import pyfortianalyzer

# Initialize the API client
faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="your-api-token"
)

# Get all FortiGates
devices = faz.fortigates.all()
print(devices)
```

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

### FortiAnalyzer Task List Example Response

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/types.md

An example response containing a list of background tasks, detailing their ID, name, status, and progress. This is typically returned by the System.tasks() API call.

```python
{
    "data": [
        {
            "id": 1,
            "name": "Device Sync",
            "status": 0,
            "percent": 100
        },
        {
            "id": 2,
            "name": "Log Indexing",
            "status": 1,
            "percent": 45
        }
    ],
    "status": {
        "code": 0,
        "message": "OK"
    },
    "url": "/task/task"
}
```

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

### FortiAnalyzer System Status Example Response

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/types.md

An example of a response object for system status, showing current version, serial, and admin domain. This is typically returned by the System.status() API call.

```python
{
    "data": {
        "version": "v7.2.0",
        "serial": "FAZ-12345",
        "admin_domain": "root"
    },
    "status": {
        "code": 0,
        "message": "OK"
    },
    "url": "/sys/status"
}
```

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

### Full Usage Pattern Example

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/api-class.md

Demonstrates a typical workflow: initializing the Api client and accessing its properties to interact with FortiAnalyzer resources. It also shows how to specify a custom ADOM for a specific operation.

```python
import pyfortianalyzer

# Initialize the API client
faz = pyfortianzer.api(
    host="https://fortianalyzer.example.com",
    token="your-api-token"
)

# Access resources through properties
adoms = faz.adoms.all()
fortigates = faz.fortigates.all()
system_status = faz.system.status()

# Optional: use custom adom for a specific operation
result = faz.fortigates.all(adom="custom-domain")
```

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

### FortiAnalyzer API Request Example

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/fortianalyzer-base.md

Demonstrates the process of making a request to the FortiAnalyzer API, from a high-level Python call to the final JSON-RPC payload and HTTP details.

```python
# High-level call
adoms = faz.adoms.all(name="root")

# Translated to:
params = {
    "url": "/dvmdb/adom/root"
}
method = "get"

# Formatted as JSON-RPC:
{
    "method": "get",
    "params": [
        {
            "url": "/dvmdb/adom/root"
        }
    ]
}

# Sent via HTTP POST to:
https://fortianalyzer.example.com/jsonrpc
# With headers:
{
    "Authorization": "Bearer {token}"
}
```

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

### FortiAnalyzer Base Class Initialization

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/fortianalyzer-base.md

This example shows how subclasses should initialize the FortiAnalyzer base class using the super() constructor. It requires a reference to the parent API instance.

```python
from pyfortianalyzer.core.fortianalyzer import FortiAnalyzer

class CustomResource(FortiAnalyzer):
    def __init__(self, **kwargs):
        super(CustomResource, self).__init__(**kwargs)
```

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

### FortiAnalyzer API Response Example

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/fortianalyzer-base.md

Illustrates the structure of a response received from the FortiAnalyzer API and how it is processed into a more usable format.

```python
# Response from FortiAnalyzer:
{
    "result": [
        {
            "data": {...},
            "status": {
                "code": 0,
                "message": "OK"
            },
            "url": "/dvmdb/adom/root"
        }
    ]
}

# Extracted and returned as:
{
    "data": {...},
    "status": {
        "code": 0,
        "message": "OK"
    },
    "url": "/dvmdb/adom/root"
}
```

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

### Get System Status

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Retrieves the current status of the FortiAnalyzer system, including version and serial number. This is a GET request.

```python
result = faz.system.status()
```

```json
{
    "method": "get",
    "params": [{
        "url": "/sys/status"
    }]
}
```

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

### Manage FortiGates

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/api-class.md

Access the `fortigates` property to manage FortiGate devices. Examples include retrieving all devices or adding a new one.

```python
all_fortigates = faz.fortigates.all()
new_device = faz.fortigates.add(serial="FGT60FTK1234ABCD")
```

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

### Example FortiGate Device Response

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/types.md

Illustrates a typical response object containing a FortiGate device's details. This format is returned when querying device information from FortiAnalyzer.

```json
{
    "data": {
        "name": "FortiGate-VM64-1",
        "sn": "FGT60FTK1234ABCD",
        "hostname": "fgt-vm64-1",
        "platform_str": "FortiGate-60F",
        "ip": "192.168.1.100",
        "dev_status": 1,
        "os_type": 0,
        "os_ver": "7.2.0",
        "maxvdom": 10,
        "mgmt_mode": 2,
        "latitude": 40.7128,
        "longitude": -74.0060,
        "desc": "Branch office firewall",
        "meta fields": {
            "location": "New York",
            "department": "IT"
        },
        "oid": 3999
    },
    "status": {
        "code": 0,
        "message": "OK"
    },
    "url": "/dvmdb/adom/root/device/FortiGate-VM64-1"
}
```

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

### Access System Endpoints

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/api-class.md

Utilize the `system` property for system-level operations. This snippet shows how to get the system status and initiate a reboot.

```python
system_status = faz.system.status()
faz.system.reboot(message="Maintenance reboot")
```

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

### Load Configuration from JSON File

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

Configure the PyFortiAnalyzer API by loading settings from a JSON configuration file. This approach centralizes configuration and is suitable for applications with complex setup requirements.

```json
{
    "fortianalyzer": {
        "host": "https://fortianalyzer.example.com",
        "token": "api-token-here",
        "adom": "root",
        "verify": true
    }
}
```

```python
import json
import pyfortianalyzer

# config.json
"""
{
    "fortianalyzer": {
        "host": "https://fortianalyzer.example.com",
        "token": "api-token-here",
        "adom": "root",
        "verify": true
    }
}
"""

with open('config.json', 'r') as f:
    config = json.load(f)
    faz_config = config['fortianalyzer']

faz = pyfortianalyzer.api(**faz_config)
```

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

### Get Single FortiGate

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/getting-started.md

Fetches details for a specific FortiGate by its name. Displays the device name if found, or a 'not found' message.

```python
result = faz.fortigates.all(fortigate="device-name")

if result['status']['code'] == 0:
    device = result['data']
    print(f"Found: {device['name']}")
else:
    print("Device not found")
```

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

### Custom API Request

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/README.md

Make a custom API request to any FortiAnalyzer endpoint not natively supported by the library. This example retrieves device meta information.

```python
faz_custom_request = fortianalyzer.system.custom_request(
    params={
        "url": "/dvmdb/adom/root/device",
        "option": [
            "get meta"
        ]
    },
    method="get"
)
print(json.dumps(faz_custom_request, indent=4))
```

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

### Custom API Request

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/getting-started.md

Makes a custom GET request to an unsupported FortiAnalyzer API endpoint, such as retrieving device metadata. Prints the raw result.

```python
result = faz.system.custom_request(
    params={
        "url": "/dvmdb/adom/root/device",
        "option": ["get", "meta"]
    },
    method="get"
)
print(result)
```

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

### System Module

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/exports.md

Manage system-level configurations and status using the System class. Perform custom requests, check HA status, reboot the system, get status, and manage tasks.

```APIDOC
## System.custom_request

### Description
Execute a custom API request to the FortiAnalyzer.

### Method
`custom_request(params: dict = None, method: str = "get") -> dict`

### Parameters
#### Request Body
- **params** (dict) - Optional - Parameters for the API request.
- **method** (str) - Optional - The HTTP method to use for the request (default: "get").
```

```APIDOC
## System.ha

### Description
Retrieve the High Availability (HA) status of the FortiAnalyzer.

### Method
`ha() -> dict`
```

```APIDOC
## System.reboot

### Description
Reboot the FortiAnalyzer system.

### Method
`reboot(message: str = None) -> dict`

### Parameters
#### Request Body
- **message** (str) - Optional - A message to display during the reboot process.
```

```APIDOC
## System.status

### Description
Get the current status of the FortiAnalyzer system.

### Method
`status() -> dict`
```

```APIDOC
## System.tasks

### Description
Retrieve information about system tasks. You can get all tasks, a specific task by ID, or filter tasks.

### Method
`tasks(task: int = None, filter: list = None, loadsub: int = 0) -> dict`

### Parameters
#### Query Parameters
- **task** (int) - Optional - The ID of a specific task to retrieve.
- **filter** (list) - Optional - A list of filters to apply to the task query.
- **loadsub** (int) - Optional - Parameter to load subtasks (default: 0).
```

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

### Context Manager for FortiAnalyzer Connection

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

Utilize a context manager to handle the lifecycle of a FortiAnalyzer connection, ensuring resources are managed appropriately. This pattern simplifies connection setup and teardown.

```python
import pyfortianalyzer

class FortiAnalyzerConnection:
    def __init__(self, host, token, adom="root", verify=True):
        self.faz = pyfortianalyzer.api(
            host=host,
            token=token,
            adom=adom,
            verify=verify
        )
    
    def __enter__(self):
        return self.faz
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        # Cleanup if needed
        pass

# Usage
with FortiAnalyzerConnection("https://fortianalyzer.example.com", "token") as faz:
    devices = faz.fortigates.all()
```

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

### Get HA Status

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Fetches the High Availability (HA) status of the FortiAnalyzer system. This is a GET request.

```python
result = faz.system.ha()
```

```json
{
    "method": "get",
    "params": [{
        "url": "/sys/ha/status"
    }]
}
```

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

### Basic Configuration (Minimal)

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

Instantiate the Api client with minimal required parameters. Uses default values for adom and verify.

```python
import pyfortianalyzer

faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="my-api-token"
)
# Uses default adom="root" and verify=True
```

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

### Get Specific Task Details

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Fetches the details or lines for a specific task identified by its ID. This is a GET request.

```python
result = faz.system.tasks(task=1)
```

```json
{
    "method": "get",
    "params": [{
        "url": "/task/task/1/line"
    }]
}
```

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

### pyfortianalyzer API Entry Point and Resource Managers

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/getting-started.md

Demonstrates initializing the Api client and accessing different resource managers for ADOMs, FortiGates, and system status.

```python
import pyfortianalyzer

faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="api-token"
)

# ADOMs (Administrative Domains)
faz.adoms.all()

# FortiGates (Managed devices)
faz.fortigates.all()

# System (FortiAnalyzer system operations)
faz.system.status()
```

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

### Import and Instantiate API Client

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/README.md

Import the library and create an API instance by providing the FortiAnalyzer host and an API token. The 'adom' and 'verify' parameters are optional.

```python
import pyfortianalyzer
fortianalyzer = pyfortianalyzer.api(
    host = "https://fortianalyzer.example.com",
    token = "<api_token_from_faz>"
)
```

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

### Type Hint in Docstring Example

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/exports.md

Type definitions are provided within docstrings, as shown in this example of a method signature with type hints.

```python
def all(self, name: str = None) -> dict:
    """..."""
```

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

### Example ADOM Object Response

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/types.md

An example of the data returned for ADOM objects, showing a list of ADOMs with their names and OIDs within the standard API response structure.

```python
{
    "data": [
        {
            "name": "root",
            "oid": 1
        },
        {
            "name": "custom_adom",
            "oid": 2
        }
    ],
    "status": {
        "code": 0,
        "message": "OK"
    },
    "url": "/dvmdb/adom"
}
```

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

### Initialize PyFortianalyzer API

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/README.md

Instantiate the API client with your FortiAnalyzer host and an API token. This is the first step before making any requests.

```python
import pyfortianalyzer

faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="api-token"
)
```

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

### Api.__init__

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/api-class.md

Initializes the FortiAnalyzer API client with connection parameters. This is the primary method for establishing a connection to your FortiAnalyzer instance.

```APIDOC
## Api.__init__

### Description
Initializes the FortiAnalyzer API client with connection parameters.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
```python
def __init__(self, host: str, token: str, adom: str="root", verify: bool=True, **kwargs)
```

### Parameters
- **host** (str) - Required - The URL of the FortiAnalyzer instance (e.g., `https://fortianalyzer.example.com`)
- **token** (str) - Required - API authentication token from FortiAnalyzer
- **adom** (str) - Optional - Default ADOM (Administrative Domain) name. Used as fallback for operations that accept an adom parameter. Defaults to "root".
- **verify** (bool) - Optional - Whether to verify SSL/TLS certificates in requests. Defaults to True.
- **kwargs** (dict) - Optional - Additional keyword arguments (reserved for future use)

### Returns
`Api` instance

### Raises
None

### Example
```python
import pyfortianalyzer

faz = pyfortianer.api(
    host="https://fortianalyzer.example.com",
    token="my-api-token-here"
)

# With custom ADOM and SSL verification disabled
faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="my-api-token-here",
    adom="custom-adom",
    verify=False
)
```
```

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

### Initialize API with Environment Variables

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/getting-started.md

Configure the FortiAnalyzer API client by reading connection details from environment variables. Ensure these variables are set before running the script.

```python
import os
import pyfortianalyzer

faz = pyfortianalyzer.api(
    host=os.getenv('FAZ_HOST'),
    token=os.getenv('FAZ_TOKEN'),
    adom=os.getenv('FAZ_ADOM', 'root'),
    verify=os.getenv('FAZ_VERIFY_SSL', 'true').lower() == 'true'
)
```

```bash
export FAZ_HOST="https://fortianalyzer.example.com"
export FAZ_TOKEN="your-api-token"
export FAZ_ADOM="root"
export FAZ_VERIFY_SSL="true"
```

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

### Get ADOM

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/MANIFEST.md

Retrieves details for a specific administrative domain (ADOM) by its name.

```APIDOC
## GET /dvmdb/adom/{name}

### Description
Retrieves details for a specific administrative domain (ADOM) by its name.

### Method
GET

### Endpoint
/dvmdb/adom/{name}

#### Path Parameters
- **name** (string) - Required - The name of the ADOM to retrieve.
```

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

### Get Task

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/MANIFEST.md

Retrieves details for a specific task by its ID, including log lines.

```APIDOC
## GET /task/task/{id}/line

### Description
Retrieves details for a specific task by its ID, including log lines.

### Method
GET

### Endpoint
/task/task/{id}/line

#### Path Parameters
- **id** (string) - Required - The ID of the task.
```

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

### Get Specific Task

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Retrieves detailed information and lines for a specific task identified by its ID.

```APIDOC
## GET /task/task/{id}/line

### Description
Retrieves detailed information and lines for a specific task identified by its ID.

### Method
GET

### Endpoint
/task/task/{id}/line

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

### Request Example
```json
{
    "method": "get",
    "params": [
        {
            "url": "/task/task/1/line"
        }
    ]
}
```

### Response
#### Success Response (200)
- **data** (array) - Task lines/details
- **status.code** (integer) - 0 for success

#### Response Example
```json
{
    "data": [
        "Task line 1",
        "Task line 2"
    ],
    "status": {
        "code": 0
    }
}
```
```

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

### Establish First Connection

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/index.md

Connect to your FortiAnalyzer instance using your host URL and API token. This initializes the API client for subsequent requests.

```python
import pyfortianalyzer
faz = pyfortianalyzer.api(
    host="https://your-fortianalyzer.com",
    token="your-api-token"
)
```

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

### Get Device

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/MANIFEST.md

Retrieves details for a specific device within a specified administrative domain (ADOM).

```APIDOC
## GET /dvmdb/adom/{adom}/device/{name}

### Description
Retrieves details for a specific device within a specified administrative domain (ADOM).

### Method
GET

### Endpoint
/dvmdb/adom/{adom}/device/{name}

#### Path Parameters
- **adom** (string) - Required - The name of the ADOM.
- **name** (string) - Required - The name of the device.
```

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

### Access ADOMs

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/api-class.md

Use the `adoms` property to manage Administrative Domains. This example retrieves all ADOMs.

```python
all_adoms = faz.adoms.all()
```

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

### Project File Structure

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/README.md

Illustrates the directory and file layout of the PyFortiAnalyzer project. Useful for understanding project organization and locating specific documentation files.

```bash
.
├── README.md                          # This file
├── index.md                           # Navigation and overview
├── getting-started.md                 # Quick start and common tasks
├── types.md                           # Data types and structures
├── configuration.md                   # Setup and configuration
├── endpoints.md                       # API endpoints and schemas
├── errors.md                          # Error handling
├── exports.md                         # Public API exports
└── api-reference/                     # Detailed class documentation
    ├── api-class.md                   # Api class
    ├── adoms.md                       # ADOMs class
    ├── fortigates.md                  # FortiGates class
    ├── system.md                      # System class
    └── fortianalyzer-base.md          # FortiAnalyzer base class
```

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

### List Tasks

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Retrieves a list of tasks running on the FortiAnalyzer. Supports filtering by task attributes. This is a GET request.

```python
result = faz.system.tasks()
result = faz.system.tasks(filter=["status", "==", 1])
```

```json
{
    "method": "get",
    "params": [{
        "url": "/task/task",
        "filter": ["status", "==", 1],
        "loadsub": 0
    }]
}
```

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

### Initialize API with Environment Variables

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

Load API connection details from environment variables to initialize the PyFortiAnalyzer client. Ensure the necessary environment variables (FAZ_HOST, FAZ_TOKEN, FAZ_ADOM, FAZ_VERIFY_SSL) are set.

```python
import os
import pyfortianalyzer

# Load from environment
HOST = os.getenv('FAZ_HOST', 'https://fortianalyzer.example.com')
TOKEN = os.getenv('FAZ_TOKEN')
ADOM = os.getenv('FAZ_ADOM', 'root')
VERIFY_SSL = os.getenv('FAZ_VERIFY_SSL', 'true').lower() == 'true'

# Initialize
faz = pyfortianalyzer.api(
    host=HOST,
    token=TOKEN,
    adom=ADOM,
    verify=VERIFY_SSL
)
```

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

### Initialize PyFortianalyzer API

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/index.md

Initialize the API client with host, token, and optional ADOM and verification settings. Ensure required parameters are provided.

```python
faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",  # Required
    token="api-token",                          # Required
    adom="root",                                # Optional, defaults to "root"
    verify=True                                 # Optional, defaults to True
)
```

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

### Get Single Device

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Retrieves details for a specific FortiGate device identified by its name within a given ADOM.

```APIDOC
## Get Single Device

### Description
Retrieves details for a specific FortiGate device identified by its name within a given ADOM.

### Method
GET

### Endpoint
/dvmdb/adom/{adom}/device/{name}

### Parameters
#### Path Parameters
- **adom** (string) - Required - The name of the ADOM containing the device.
- **name** (string) - Required - The name of the FortiGate device to retrieve.

### Response
#### Success Response (200 OK with status.code: 0)
- **data** (object) - FortiGate device object
  - **data.name** (string) - Device name
  - **data.sn** (string) - Serial number
- **status.code** (integer) - 0 for success

#### Error Response
- **200 OK** with `status.code: -3` — Device not found
```

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

### Recommended PyFortiAnalyzer Usage

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/exports.md

This is the recommended way to import and initialize the PyFortiAnalyzer client. Access managers through properties like faz.adoms, faz.fortigates, and faz.system.

```python
# Recommended way
import pyfortianalyzer

faz = pyfortianalyzer.api(host="...", token="...")
# Access managers through properties:
faz.adoms
faz.fortigates
faz.system
```

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

### Initialize Api Client

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/api-class.md

Instantiate the Api client with connection details. You can specify a custom ADOM and control SSL verification.

```python
import pyfortianalyzer

faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="my-api-token-here"
)

# With custom ADOM and SSL verification disabled
faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="my-api-token-here",
    adom="custom-adom",
    verify=False
)
```

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

### Checking API Response Status

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/getting-started.md

Example of how to check the status code of an API response and handle success or error cases.

```python
result = faz.fortigates.all()

if result['status']['code'] == 0:
    # Success
    for device in result['data']:
        print(device['name'])
else:
    # Error
    print(f"Error: {result['status']['message']}")
```

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

### Initialize pyfortianalyzer API and access FortiGates manager

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/fortigates.md

This snippet shows how to initialize the pyfortianalyzer API client with host and token, and then access the FortiGates manager instance which is automatically created.

```python
import pyfortianalyzer

faz = pyfortianalyzer.api(host="https://fortianalyzer.example.com", token="token")
fortigates_manager = faz.fortigates  # Automatically created with api instance
```

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

### Get Single Device

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Retrieves details for a specific FortiGate device by its name within a specified ADOM. The ADOM defaults to 'root'.

```python
result = faz.fortigates.all(fortigate="FortiGate-VM64-1")
```

```json
{
    "method": "get",
    "params": [{
        "url": "/dvmdb/adom/root/device/FortiGate-VM64-1",
        "option": ["get meta"]
    }]
}
```

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

### Production Configuration (Recommended)

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

Configure the Api client for production use with explicit settings for host, token, adom, and SSL verification.

```python
import pyfortianalyzer

faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="secure-api-token-here",
    adom="root",
    verify=True
)
```

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

### Endpoint Documentation

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/MANIFEST.md

Details on how endpoints are documented, including HTTP method, path, Python call examples, request/response formats, parameters, and status codes.

```APIDOC
## Endpoint Documentation

### Description
Documentation for each endpoint includes the HTTP method and path, Python code that calls it, the request JSON format, a request parameter table, the response schema table, status codes, and example request/response pairs.

### Method
[HTTP method: GET, POST, PUT, DELETE, etc.]

### Endpoint
[Full endpoint path with any path parameters]

### Parameters
#### Request Parameters
- **param1** (type) - Required/Optional - Description

#### Request Body
- **field1** (type) - Required/Optional - Description

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (Status Codes)
- **field1** (type) - Description

#### Response Example
```json
{
  "example": "response body"
}
```
```

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

### System.status()

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/types.md

Retrieves the current system status of the FortiAnalyzer instance, including version, serial number, and administrative domain.

```APIDOC
## System.status()

### Description
Retrieves the current system status of the FortiAnalyzer instance.

### Method
GET

### Endpoint
/sys/status

### Response
#### Success Response (200)
- **version** (str) - FortiAnalyzer version string (e.g., "v7.2.0")
- **serial** (str) - System serial number
- **admin_domain** (str) - Current administrative domain

### Response Example
{
  "data": {
    "version": "v7.2.0",
    "serial": "FAZ-12345",
    "admin_domain": "root"
  },
  "status": {
    "code": 0,
    "message": "OK"
  },
  "url": "/sys/status"
}
```

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

### Verify Connection Host and Accessibility

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

Check if the host URL is correct and accessible, ensure FortiAnalyzer is running, and verify network connectivity.

```text
Verify:
- host URL is correct and accessible
- FortiAnalyzer is running
- Network connectivity exists
```

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

### Get Specific ADOM

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Retrieves details for a specific ADOM identified by its name. This endpoint returns a single ADOM object containing its name and object ID.

```APIDOC
## GET /dvmdb/adom/{name}

### Description
Retrieves details for a specific ADOM identified by its name. This endpoint returns a single ADOM object containing its name and object ID.

### Method
GET

### Endpoint
/dvmdb/adom/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the ADOM to retrieve.

### Request Example
```json
{
    "method": "get",
    "params": [{
        "url": "/dvmdb/adom/root"
    }]
}
```

### Response
#### Success Response (200)
- **data** (object) - Single ADOM object
  - **data.name** (string) - ADOM name
  - **data.oid** (integer) - Object ID
- **status.code** (integer) - 0 for success

### Status Codes
- `200 OK` with `status.code: 0` — Success
- `200 OK` with `status.code: -3` — ADOM not found
```

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

### Add a FortiGate

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/README.md

Add a new FortiGate to the Device Manager using its serial number. This requires the minimum necessary fields.

```python
faz_fortigate_add = fortianalyzer.fortigates.add(
    serial = "FGT60FTK1234ABCD"
)
print(faz_fortigate_add)
```

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

### Get Specific ADOM by Name

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Retrieve details for a particular ADOM by specifying its name. This is useful for accessing configuration or status of a single ADOM. The ADOM must exist.

```python
result = faz.adoms.all(name="root")
```

```json
{
    "method": "get",
    "params": [{
        "url": "/dvmdb/adom/root"
    }]
}
```

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

### Request/Response Flow

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/fortianalyzer-base.md

Illustrates how to construct API requests using JSON-RPC and how responses are formatted by FortiAnalyzer.

```APIDOC
## Request Format

### High-level Call Example
```python
adoms = faz.adoms.all(name="root")
```

### Translated to JSON-RPC Parameters
```python
params = {
    "url": "/dvmdb/adom/root"
}
method = "get"
```

### Formatted as JSON-RPC Request
```json
{
    "method": "get",
    "params": [
        {
            "url": "/dvmdb/adom/root"
        }
    ]
}
```

### HTTP POST Request Details
- **URL**: `https://fortianalyzer.example.com/jsonrpc`
- **Headers**: `{"Authorization": "Bearer {token}"}`

## Response Format

### FortiAnalyzer Response Example
```json
{
    "result": [
        {
            "data": {...},
            "status": {
                "code": 0,
                "message": "OK"
            },
            "url": "/dvmdb/adom/root"
        }
    ]
}
```

### Extracted and Returned Response
```json
{
    "data": {...},
    "status": {
        "code": 0,
        "message": "OK"
    },
    "url": "/dvmdb/adom/root"
}
```
```

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

### Filter Array Usage Examples

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/types.md

Demonstrates how to use the filter array to retrieve tasks based on specific criteria. Use this to narrow down results in methods like system.tasks().

```python
# Get tasks with status equal to 1
tasks = faz.system.tasks(filter=["status", "==", 1])
```

```python
# Get tasks where name contains "Sync"
tasks = faz.system.tasks(filter=["name", "contains", "Sync"])
```

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

### Api Constructor Options

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

The Api constructor accepts parameters to configure connection and default behavior. These include host, token, adom, and SSL verification.

```python
api = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="api-token",
    adom="root",
    verify=True,
    **kwargs
)
```

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

### Initialize System Manager

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/system.md

The System manager is automatically created with an Api instance and should not be instantiated directly. It requires an Api instance passed via kwargs.

```python
import pyfortianalyzer

faz = pyfortianzer.api(host="https://fortianalyzer.example.com", token="token")
system_manager = faz.system  # Automatically created with api instance
```

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

### System.tasks()

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/types.md

Retrieves a list of background tasks running on the FortiAnalyzer, including their ID, name, status, and completion percentage.

```APIDOC
## System.tasks()

### Description
Retrieves a list of background tasks in FortiAnalyzer.

### Method
GET

### Endpoint
/task/task

### Response
#### Success Response (200)
- **id** (int) - Task identifier
- **name** (str) - Task name or description
- **status** (int) - Task status code
- **percent** (int) - Completion percentage (0-100)

### Response Example
{
  "data": [
    {
      "id": 1,
      "name": "Device Sync",
      "status": 0,
      "percent": 100
    },
    {
      "id": 2,
      "name": "Log Indexing",
      "status": 1,
      "percent": 45
    }
  ],
  "status": {
    "code": 0,
    "message": "OK"
  },
  "url": "/task/task"
}
```

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

### List All FortiGates

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/README.md

Retrieve and print the names of all FortiGates managed by FortiAnalyzer. This retrieves all data for each FortiGate.

```python
faz_fortigates = fortianalyzer.fortigates.all()
for faz_fortigate in faz_fortigates['data']:
    print(faz_fortigate['name'])
```

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

### Get FortiAnalyzer System Status

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/system.md

Retrieves the current operational status of the FortiAnalyzer system, including version, license, and health metrics. Check the 'status.code' field for success (0) or errors.

```python
import json

# Get system status
sys_status = faz.system.status()

if sys_status['status']['code'] == 0:
    status_data = sys_status['data']
    print(f"FortiAnalyzer Version: {status_data.get('version', 'Unknown')}")
    print(f"Serial: {status_data.get('serial', 'Unknown')}")
    print(json.dumps(status_data, indent=2))
else:
    print(f"Status check failed: {sys_status['status']['message']}")
```

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

### Import pyfortianalyzer Package

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/exports.md

Import the main pyfortianalyzer package to access its top-level API factory.

```python
import pyfortianalyzer
```

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

### Basic FortiGate Request with Error Handling

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/index.md

Fetches all FortiGates and prints their names if the request is successful. Handles potential API errors by printing an error message.

```python
result = faz.fortigates.all()

if result['status']['code'] == 0:
    for device in result['data']:
        print(device['name'])
else:
    print(f"Error: {result['status']['message']}")
```

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

### Configuring Default ADOM in pyfortianalyzer

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/getting-started.md

Shows how to set a default ADOM when initializing the Api client and how to override it for specific calls.

```python
# Default ADOM is "root"
faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="token"
)

# Use a different default ADOM
faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="token",
    adom="custom-adom"
)

# Override for specific calls
result = faz.fortigates.all(adom="another-adom")
```

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

### Handle SSL Certificate Verification Failures

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

Solutions for SSL certificate verification errors. Use `verify=True` with a valid certificate, disable verification with `verify=False` (development only), or install the CA certificate in your Python environment.

```text
Solutions:
- Use verify=True with a valid certificate
- Or disable verification only in development: verify=False
- Or install the CA certificate in your Python environment
```

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

### pyfortianalyzer.api

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/exports.md

Factory function to create an API client instance for interacting with FortiAnalyzer.

```APIDOC
## pyfortianalyzer.api

### Description
Factory function to create an API client instance for interacting with FortiAnalyzer.

### Usage
```python
import pyfortianalyzer

faz = pyfortianalyzer.api(
    host="https://fortianalyzer.example.com",
    token="api-token"
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters for `pyfortianalyzer.api` function:
- **host** (str) - Required - FortiAnalyzer base URL.
- **token** (str) - Required - API authentication token.
- **adom** (str) - Optional - Default ADOM to use (defaults to "root").
- **verify** (bool) - Optional - SSL/TLS verification flag (defaults to True).
- **kwargs** - Additional keyword arguments.

### Response
#### Success Response
Returns an instance of `pyfortianalyzer.core.api.Api`.

#### Response Example
```python
# Example of the returned object (not a direct response)
# faz = pyfortianalyzer.api(...)
```
```

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

### Add FortiGate

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/getting-started.md

Adds a new FortiGate device to the FortiAnalyzer. Requires serial number, name, and an optional description. Reports success or failure.

```python
result = faz.fortigates.add(
    serial="FGT60FTK1234ABCD",
    name="Branch-Office-FW",
    description="Firewall at branch"
)

if result['status']['code'] == 0:
    print("Device added successfully")
else:
    print(f"Error: {result['status']['message']}")
```

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

### system

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/api-reference/api-class.md

Provides access to FortiAnalyzer system-level endpoints. Use this property for system operations and custom requests.

```APIDOC
## system

### Description
Provides access to FortiAnalyzer system-level endpoints. Returns a `System` instance configured with this API instance.

### Method Signature
```python
@property
def system(self) -> System
```

### Returns
`System` object for system operations and custom requests

### Example
```python
system_status = faz.system.status()
faz.system.reboot(message="Maintenance reboot")
```
```

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

### List All ADOMs in FortiAnalyzer

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/endpoints.md

Use this method to retrieve a list of all available ADOMs on the FortiAnalyzer. Ensure you have the correct host and authentication token configured.

```python
result = faz.adoms.all()
```

```json
{
    "method": "get",
    "params": [{
        "url": "/dvmdb/adom"
    }]
}
```

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

### Tasks

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/index.md

Retrieves a list of all tasks running on the FortiAnalyzer.

```APIDOC
## Tasks

### Description
Retrieves a list of all tasks running on the FortiAnalyzer.

### Method
GET

### Endpoint
/task/task
```

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

### Device Add Parameters Structure

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/types.md

Defines the parameters required for adding a new FortiGate device using the FortiGates.add() method. Includes fields for serial number, name, management mode, credentials, description, and metadata.

```python
{
    "serial": str,
    "name": str,
    "mgmt_mode": str,
    "adm_usr": str,
    "adm_pass": str,
    "description": str,
    "meta_fields": dict
}
```

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

### Add Device

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/MANIFEST.md

Adds a new device to the FortiAnalyzer management. This is an execution command.

```APIDOC
## EXEC /dvm/cmd/add/device

### Description
Adds a new device to the FortiAnalyzer management. This is an execution command.

### Method
EXEC

### Endpoint
/dvm/cmd/add/device
```

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

### Initialize API with SSL Verification Disabled

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/getting-started.md

Initialize the PyFortiAnalyzer API client with SSL verification disabled. This is suitable for development or testing with self-signed certificates but is not recommended for production environments.

```python
# For self-signed certificates or testing
faz = pyfortianalyzer.api(
    host="https://fortianalyzer.internal",
    token="token",
    verify=False  # Not recommended for production
)
```

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

### Per-Tenant Multi-Tenancy Configuration

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

Manage multiple FortiAnalyzer instances for different tenants by creating separate API objects. This pattern is useful when interacting with distinct tenant environments.

```python
import pyfortianalyzer

# Create separate API instances for different tenants
tenants = {
    'customer_a': 'https://fortianalyzer.example.com',
    'customer_b': 'https://fortianalyzer.example.com'
}

faz_instances = {}
for tenant, host in tenants.items():
    faz_instances[tenant] = pyfortianalyzer.api(
        host=host,
        token=f"token-for-{tenant}",
        adom=tenant
    )

# Usage
devices_a = faz_instances['customer_a'].fortigates.all()
devices_b = faz_instances['customer_b'].fortigates.all()
```

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

### List All FortiGates

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/index.md

Retrieve a list of all FortiGate devices managed by FortiAnalyzer. Check the status code to ensure the operation was successful before accessing the data.

```python
result = faz.fortigates.all()
if result['status']['code'] == 0:
    print(result['data'])
```

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

### Reboot

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/index.md

Initiates a system reboot for the FortiAnalyzer.

```APIDOC
## Reboot

### Description
Initiates a system reboot for the FortiAnalyzer.

### Method
EXEC

### Endpoint
/sys/reboot
```

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

### Verify Authentication Token and Permissions

Source: https://github.com/bestseller/pyfortianalyzer/blob/master/_autodocs/configuration.md

Ensure the API token is correct, has API access enabled in FortiAnalyzer, and possesses the necessary permissions for required operations.

```text
Verify:
- token is correct
- token has API access enabled in FortiAnalyzer
- token permissions include required operations
```