# Omada Cloud Northbound API Documentation

## Official API Documentation

The Omada Cloud northbound API documentation is available at:
- **EU Region**: https://euw1-omada-northbound.tplinkcloud.com/doc.html#/home
- **US Region**: https://usw1-omada-northbound.tplinkcloud.com/doc.html#/home
- **Asia Region**: https://ap1-omada-northbound.tplinkcloud.com/doc.html#/home

## API Base URL Structure

Our implementation uses:
```
${OMADA_NORTHBOUND_BASE}/openapi/v1/omada/${OMADA_ID}
```

Example:
```
https://euw1-omada-northbound.tplinkcloud.com/openapi/v1/omada/b7335e3ad40ef0df060a922dcf5abdf5
```

## Authentication

The API documentation should contain the correct authentication endpoint. Based on our implementation, we're trying:

1. `${OMADA_CONTROLLER_BASE}/${OMADA_ID}/openapi/login`
2. `${OMADA_CONTROLLER_BASE}/openapi/login`
3. `${OMADA_NORTHBOUND_BASE}/openapi/v1/omada/${OMADA_ID}/login`

**Note**: Check the official documentation for the exact authentication endpoint format.

## API Endpoints Used

### Sites
- `GET /sites` - List all sites
- `GET /sites/{siteId}` - Get site details

### Devices
- `GET /sites/{siteId}/devices` - List devices for a site
- `GET /sites/{siteId}/devices/{deviceId}` - Get device details
- `POST /sites/{siteId}/devices/{deviceId}/reboot` - Reboot device
- `POST /sites/{siteId}/devices/{deviceId}/locate` - Locate device

### Gateway Configuration
- `GET /sites/{siteId}/devices/{deviceId}/wan` - Get WAN configuration
- `PUT /sites/{siteId}/devices/{deviceId}/wan` - Update WAN configuration
- `POST /sites/{siteId}/devices/{deviceId}/vpn` - Configure VPN

### Switch Configuration
- `GET /sites/{siteId}/devices/{deviceId}/ports` - Get switch ports
- `POST /sites/{siteId}/devices/{deviceId}/ports/{portIndex}/vlan` - Set port VLAN
- `PUT /sites/{siteId}/devices/{deviceId}/ports/{portIndex}` - Toggle port

### Wireless (SSID)
- `GET /sites/{siteId}/wlans` - List SSIDs
- `POST /sites/{siteId}/wlans` - Create SSID
- `PUT /sites/{siteId}/wlans/{wlanId}` - Update SSID

### Clients
- `GET /sites/{siteId}/clients` - List clients
- `POST /sites/{siteId}/clients/{clientId}/block` - Block client
- `POST /sites/{siteId}/clients/{clientId}/unblock` - Unblock client

## Verifying Endpoints

To verify the correct endpoint structure:
1. Visit the API documentation URL for your region
2. Check the authentication endpoint format
3. Verify the endpoint paths match our implementation
4. Update our code if the documentation shows different paths

## Accessing the Documentation

You can access the interactive API documentation by:
1. Opening the doc.html URL in your browser
2. Using the Swagger UI interface to explore endpoints
3. Testing endpoints directly from the documentation interface (if authentication is configured)

## Next Steps

1. Review the official documentation for authentication endpoint
2. Verify all endpoint paths match the documentation
3. Update implementation if discrepancies are found
4. Test endpoints using the documentation interface