A Python proof-of-concept for interacting with the UniFi Site Manager API v1.0. This project demonstrates how to authenticate and retrieve data from your UniFi deployment through Ubiquiti's cloud-based API.

• Authentication: Secure API key-based authentication
• Host Discovery: List and retrieve information about your UniFi hosts
• Error Handling: Comprehensive error handling with rate limiting support
• Extensible: Easy to add new endpoints and functionality

• Python 3.8+
• UniFi Site Manager account (unifi.ui.com)
• API key from UniFi Site Manager

1. Clone the repository

   git clone <your-repo-url>
   cd unifiapi

2. Create virtual environment

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure API key

   # Create apikey.txt file with your API key
   echo "YOUR_API_KEY_HERE" > apikey.txt

1. Sign in to UniFi Site Manager
2. Navigate to the API section from the left navigation bar
3. Select "Create API Key"
4. Copy the generated key and store it in apikey.txt

⚠️ Security Note: Never commit your API key to version control. The .gitignore file is configured to exclude apikey.txt.

# Activate virtual environment
source venv/bin/activate

# Run the PoC
python unifi_api_poc.py

UniFi Site Manager API PoC
========================================
Using API key: UKYVN6fP...

🏠 Testing List Hosts endpoint...
Making GET request to: https://api.ui.com/v1/hosts
Response Status: 200
✅ Success! Here's the response:
{
  "data": [
    {
      "id": "70A741BD2E21000000000687DA420000000006D654490000000062CF8A31:1749156065",
      "hardwareId": "8d982da9-30ae-5e61-a6ac-0767384388d5",
      "type": "console",
      "ipAddress": "68.235.232.249",
      ...
    }
  ]
}

📊 Summary: Found 1 hosts

The current PoC supports these UniFi Site Manager API endpoints:

• GET /hosts - List all hosts in your deployment
• GET /hosts/{id} - Get detailed information about a specific host
• GET /sites - List all sites (ready to implement)
• GET /devices - List all devices (ready to implement)
• GET /isp-metrics - Get ISP performance metrics (ready to implement)

unifiapi/
├── unifi_api_poc.py      # Main PoC script
├── requirements.txt       # Python dependencies
├── apikey.txt           # Your API key (not in git)
├── .gitignore           # Git ignore rules
└── README.md            # This file

You can also use environment variables instead of apikey.txt:

export UNIFI_API_KEY="your-api-key-here"

The API has rate limits:

• Early Access (EA): 100 requests per minute
• v1 stable: 10,000 requests per minute

The client automatically handles rate limiting with 429 Too Many Requests responses.

To add support for new API endpoints, extend the UniFiSiteManagerAPI class:

def list_sites(self) -> Optional[Dict[Any, Any]]:
    """List all sites in your UniFi deployment"""
    return self._make_request("sites")

def get_isp_metrics(self) -> Optional[Dict[Any, Any]]:
    """Get ISP performance metrics"""
    return self._make_request("isp-metrics")

The client handles common error scenarios:

• 401 Unauthorized: Invalid API key
• 403 Forbidden: Insufficient permissions
• 429 Too Many Requests: Rate limiting
• Network errors: Connection timeouts

For complete API documentation, visit:

• UniFi Site Manager API Documentation

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

This is a proof-of-concept project for educational purposes. The UniFi Site Manager API is provided by Ubiquiti Inc. and may be subject to their terms of service.

"ModuleNotFoundError: No module named 'requests'"

# Make sure virtual environment is activated
source venv/bin/activate
pip install requests

"Authentication failed! Check your API key."

• Verify your API key is correct
• Ensure your UniFi account has devices connected to unifi.ui.com
• Check that your API key has the necessary permissions

"Rate limited! Retry after: X seconds"

• The API has rate limits. Wait the specified time before making more requests.

• Check the UniFi Site Manager API Documentation
• Review the error messages in the console output
• Ensure your UniFi deployment is properly connected to the cloud

Happy coding! 🎉