[← Back to AIPass](../../../README.md)

# API

**Purpose:** Centralized external API gateway — authenticated service clients for all external APIs (OpenRouter, Google, future providers).
**Module:** `aipass.api`
**Last Updated:** 2026-04-07

---

## Overview

### What I Do
- Provide authenticated service clients for external APIs (Google Drive, OpenRouter, etc.)
- Manage OAuth2 flows, credential storage, and token refresh
- Offer thread-safe service factories for concurrent consumers
- Handle API key management and validation across providers
- Provide SSL retry and connection resilience utilities

### What I Don't Do
- Host business logic — consumers own what they do with the service
- Set default models or configs — consumers provide their own
- Manage application workflows, polling loops, or orchestration

### How I Work
- **Entry Point:** `apps/api.py` -- auto-discovers and routes to modules
- **Pattern:** Standard AIPass 3-tier architecture (entry point / modules / handlers)
- **Design principle:** If it's not auth, credentials, or service factory — it doesn't belong here

---

## Commands / Usage

```bash
drone @api get-key           # Retrieve API key for provider
drone @api validate          # Validate API credentials and connection
drone @api validate google   # Validate Google OAuth2 credentials
drone @api reauth google     # Re-authenticate Google OAuth2
drone @api test              # Test OpenRouter connection status
drone @api models [--all]    # List available models from provider
drone @api status            # Check OpenRouter client status
drone @api call "prompt" --model MODEL  # Make API call to model
drone @api list-providers    # List available API providers
drone @api init              # Initialize .env template
drone @api track <gen_id>    # Track API usage metrics
drone @api stats             # Display API usage statistics
drone @api session           # Show session usage data
drone @api caller-usage <caller>  # Show usage by caller module
drone @api cleanup [days]    # Clean up old usage data *(not operational — fails with no data)*
drone @api --help            # Full help output
drone @api --version         # Show version
```

Running `drone @api` with no arguments displays module introspection (discovered modules and status).

---

## Cross-Branch API

```python
# LLM access (OpenRouter)
from aipass.api.apps.modules.openrouter_client import get_response
response = get_response(prompt="...", model="anthropic/claude-3.5-sonnet", caller="flow")

# Google Drive (or any Google API)
from aipass.api.apps.modules.google_client import get_drive_service
service = get_drive_service()                   # Single-threaded
service = get_drive_service(thread_safe=True)   # For concurrent workers

# Any Google service
from aipass.api.apps.modules.google_client import get_google_service
service = get_google_service("calendar", "v3")

# Retry utility for raw API calls
from aipass.api.apps.modules.google_client import api_call_with_retry
```

---

## Architecture

```
api/
├── __init__.py                    # Public API exports
├── apps/
│   ├── api.py                     # Entry point (module discovery, command routing)
│   ├── modules/
│   │   ├── api_key.py             # Key retrieval and validation logic
│   │   ├── openrouter_client.py   # OpenRouter API client
│   │   ├── google_client.py       # Google API services (Drive, Calendar, etc.)
│   │   └── usage_tracker.py       # Usage metrics tracking
│   └── handlers/
│       ├── auth/
│       │   ├── env.py             # Environment variable credential loading
│       │   └── keys.py            # API key storage and retrieval
│       ├── config/
│       │   └── provider.py        # Provider configuration management
│       ├── google/
│       │   ├── auth.py            # OAuth2 lifecycle, credential I/O
│       │   ├── service_factory.py # Service object factory (single + thread-safe)
│       │   └── retry.py           # SSL retry with exponential backoff
│       ├── json/
│       │   └── json_handler.py    # JSON operation logging
│       ├── openrouter/
│       │   ├── caller.py          # HTTP request execution
│       │   ├── client.py          # OpenRouter client implementation
│       │   ├── models.py          # Model discovery and listing
│       │   └── provision.py       # Provider provisioning
│       └── usage/
│           ├── aggregation.py     # Usage data aggregation
│           ├── cleanup.py         # Usage data cleanup
│           └── tracking.py        # Usage event tracking
└── README.md
```

---

## Integration Points

### Depends On
- `aipass.prax` -- structured logging via `system_logger`
- `aipass.cli` -- Rich console output formatting

### Provides To
- All branches -- authenticated external API clients
- System-wide API key management and credential validation

### Credentials
- `~/.secrets/aipass/.env` -- API keys (OpenRouter, etc.)
- `~/.secrets/aipass/google_creds.json` -- Google OAuth2 tokens
- `~/.secrets/aipass/google_client_secret.json` -- Google OAuth app config

---

*Last Updated: 2026-04-07*

---
[← Back to AIPass](../../../README.md)
