Network

airvpn.api.network

`AirSession`

Bases: Session

A requests.Session subclass for the AirVPN API with built-in rate limiting.

Automatically attaches the API key as an API-KEY header and enforces AirVPN's documented limit of 600 requests per 10 minutes to avoid getting IP banned. Requests should be made via service_request(), which handles endpoint construction, rate limiting, and response/error parsing.

Attributes:

Name	Type	Description
`BASE_URL`		Base URL for all AirVPN API requests.
`REQUESTS_MAX`		Maximum requests allowed per `REQUESTS_MAX_MINUTES` window, per AirVPN's API documentation.
`REQUESTS_MAX_MINUTES`		Length (in minutes) of AirVPN's fixed rate-limit window.
`REQUESTS_PER_MIN`		`REQUESTS_MAX` divided evenly across `REQUESTS_MAX_MINUTES`, used to scale the limit for a given `rate_window_minutes`.
`rate_window_minutes`		The instance's configured window (in minutes) used to track and enforce the request rate limit. Clamped to `REQUESTS_MAX_MINUTES`.

Parameters:

Name	Type	Description	Default
`api_key`	`str`	AirVPN API key, sent via the `API-KEY` header.	required
`rate_window_minutes`	`int`	Size of the rolling window used for rate limiting. Defaults to 5. Values above `REQUESTS_MAX_MINUTES` (10) are clamped, with a warning.	`5`

`service_request(method: Literal['get', 'post'], service: ServiceType | str, data: dict[str, str] = {}, format: Literal['json', 'xml', 'php', 'text'] = 'json', **kwargs)`

Make a rate-limited request to an AirVPN API service.

Raises:

Type	Description
`InvalidService`	if `service` isn't a ServiceType member.
`InvalidMethod`	if `method` isn't "get" or "post".
`RateLimited`	if the configured request rate limit is hit.
`APIError`	if the API responds with an error field.

`AirStatus`

Bases: StrEnum

Overall status reported by the AirVPN API/service.

Attributes:

Name	Type	Description
`OK`		Service is operating normally.
`WARNING`		Service is operating but with a non-critical issue.
`ERROR`		Service is experiencing a critical issue.

`ServiceType`

Bases: StrEnum

Identifies an AirVPN API service endpoint.

Each member's value corresponds to the path segment used to build the request URL in AirSession.service_request() (e.g. DEVICES maps to https://airvpn.org/api/devices/).

Attributes:

Name	Type	Description
`DEVICES`		Manage or list the account's registered devices.
`DNS_LISTS`		Retrieve available DNS list options.
`GENERATOR`		Generate VPN configuration files/keys.
`STATUS`		Retrieve current service/server status.
`USERINFO`		Retrieve information about the authenticated account.
`WHATISMYIP`		Retrieve the caller's public IP address.
`DISCONNECT`		Disconnect an active VPN session/device.
`NOTIFICATION`		Retrieve or manage account notifications.