# YBrowse REST API v1
Base URL: `https://your-domain.example/api/v1`. JSON request/response bodies. Protected routes use `Authorization: Bearer ACCESS_TOKEN`. Store tokens in Android Keystore. Never log tokens/passwords.

## Public
- `GET /health`
- `GET /app/version` — version code, minimum code, force update metadata.

## Authentication
- `POST /auth/register` — `{name,phone,email?,address?,password,device_id,device_name?,device_public_key?}`; unique phone/email, starts one 72-hour server-time trial and binds the first device.
- `POST /auth/login` — `{phone,password,device_id,device_name?}`; another active device is rejected.
- `POST /auth/refresh` — `{refresh_token}`; rotates access and refresh tokens.
- `POST /auth/logout`
- `POST /auth/change-password` — `{current_password,new_password}`; revokes other sessions.

## Device / subscription
- `GET /device/status`
- `POST /device/register` — `{device_id,device_name?}`; verifies the already-bound device.
- `POST /device/replacement-request` — `{new_device_id,device_name?}`; requires admin approval.
- `GET /trial/status`
- `GET /subscription/status`
- `GET /subscription/plans`

## Payments
- `GET /payment/methods`
- `POST /payment/submit` — `{method_id,amount,transaction_last4,transaction_reference?}`
- `GET /payment/history`
Submitted requests remain pending until independently verified by an admin.

## Protected content
- `GET /app/settings`
- `GET /websites`
- `GET /notifications`
- `POST /coupons/validate` — `{code}`
- `GET /youtube/search?q=...` — server-side Data API key pool; returns metadata only.
- `GET /support/tickets`
- `POST /support/ticket` — `{subject,message}`

## HTTP status
200 success, 201 created, 401 invalid session, 402 subscription/trial locked, 403 blocked/device mismatch, 404 route not found, 422 validation, 429 rate limited, 426 HTTPS required.

## Lock contract
Protected content endpoints validate subscription on every request. Payment, status, support, logout and authentication endpoints remain accessible while locked. Client must treat 402 as locked and clear premium cached content.
