# Debrid Provider API Endpoints

Audit of Retrofit interface endpoint paths for all four supported debrid providers.
Live-verified with curl against production APIs.

## Real-Debrid

| Operation | Method | Path | Verified |
|---|---|---|---|
| Request device code | `GET` | `https://api.real-debrid.com/oauth/v2/device/code` | ✅ 400 (needs client_id) |
| Exchange token | `POST` | `https://api.real-debrid.com/oauth/v2/token` | ✅ 403 (needs body) |
| Account info | `GET` | `/user` (relative, base = `https://api.real-debrid.com/rest/1.0/`) | Standard |
| Instant availability | `POST` | `/torrents/instantAvailability/{hash}` | Standard |
| Unrestrict link | `POST` | `/unrestrict/link` | Standard |

**Critical:** Real-Debrid's OAuth and REST APIs use DIFFERENT base paths:
- OAuth v2: `https://api.real-debrid.com/oauth/v2/`
- REST API: `https://api.real-debrid.com/rest/1.0/`

The Retrofit interface MUST use absolute URLs for OAuth endpoints so they override the REST base URL configured in the Hilt module.

### Common mistake
```kotlin
// WRONG — 404: /rest/1.0/oauth/device/code does not exist
@POST("https://api.real-debrid.com/rest/1.0/oauth/device/code")

// WRONG — 404: /rest/1.0/oauth/token does not exist
@POST("https://api.real-debrid.com/rest/1.0/oauth/token")

// RIGHT — live endpoints
@GET("https://api.real-debrid.com/oauth/v2/device/code")
@POST("https://api.real-debrid.com/oauth/v2/token")
```

### v2 Device code response shape
```json
{
    "device_code": "...",
    "user_code": "GCE3T2P4",
    "interval": 5,
    "expires_in": 900,
    "verification_url": "https://real-debrid.com/device",
    "direct_verification_url": "..."
}
```

Fields used in the DTO (`RealDebridDeviceCodeResponse`):
- `user_code` → `userCode` (displayed to user)
- `device_code` → `deviceCode` (used for polling)
- `interval` → `interval` (polling interval in seconds)
- `verification_url` → `verificationUrl` (where user enters code)
- `expires_in` → `expiresIn`

## AllDebrid

Base URL: `https://api.alldebrid.com/v4/` (all relative paths)

| Operation | Method | Path | Verified |
|---|---|---|---|
| Request PIN | `GET` | `/pin/get?agent=NexStream` | Standard |
| Poll PIN | `GET` | `/pin/check?agent=NexStream&pin=...` | Standard |
| Account info | `GET` | `/user?agent=NexStream&apikey=...` | Standard |

AllDebrid uses query parameters for auth (agent + apikey), not headers.

## Premiumize

Base URL: `https://www.premiumize.me/api/`

Uses static API key (no OAuth flow). Key passed via query parameter `apikey`.

## TorBox

Base URL: `https://api.torbox.app/v1/`

Uses Bearer token via Authorization header. Static key, no OAuth flow.

## Debugging endpoint issues

When a debrid client returns "Connection failed" immediately:
1. Check logcat for the actual HTTP status code (filter: `OkHttp` or `DebridAuthManager`)
2. Compare annotation URL against this reference
3. Live-test with curl before modifying code
4. Remember: absolute URLs in annotations override the Retrofit base URL