# We-MP-RSS API Quick Reference

## API Base

The FastAPI app mounts all API routers under `/api/v1/wx/` (configured in `core/base.py` as `API_BASE = "/api/v1/wx"`).

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/wx/articles` | GET | Article list (paginated: `?page=1&page_size=100`) |
| `/api/v1/wx/articles/{id}` | GET | Single article detail (`?content=true` for body) |
| `/api/v1/wx/mps` | GET | Feed/subscription list |
| `/api/v1/wx/cascade/feeds` | GET | Cascade feed status |
| `/api/v1/wx/auth/token` | POST | JWT login token |
| `/api/docs` | GET | Swagger UI |
| `/api/openapi.json` | GET | OpenAPI schema |

**Critical**: Endpoints use the *plural* form (`articles`, `mps`), not singular. `article` (singular) returns `null` with HTTP 200 — silent failure.

## Authentication

### AK-SK (API access key — for server-side scripts)

```bash
curl -H "Authorization: AK-SK {access_key}:{secret_key}" \
  "http://localhost:8001/api/v1/wx/articles?page=1&page_size=10"
```

Keys created via web UI → Access Keys. Stored in `access_keys` table. The SK is SHA256-hashed in the database; the raw SK from `.env` is sent in the header.

### JWT (Bearer — for web UI)

```bash
curl -H "Authorization: Bearer {jwt_token}" \
  "http://localhost:8001/api/v1/wx/article"
```

Used by the Vue frontend after login.

## Response Format

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "list": [...],
    "page": {"page": 1, "page_size": 100, "total": 114}
  }
}
```

## Database

SQLite at `we-mp-rss-data/db.db`. Key tables: `feeds` (subscriptions), `articles` (cached articles), `users` (admin login), `access_keys` (API keys).

## Built-in Scheduler

`ENABLE_JOB=True` enables background fetch jobs in the we-mp-rss process. `SPAN_INTERVAL=600` sets 10-min intervals. However, in practice on Chinese servers the built-in scheduler may stall — supplement with an external cron job running `fetch_articles.py` every 1-2 hours via Hermes cronjob.

## Access Key Setup (One-Time)

1. Login to `https://rss.gdcjgk.net` (admin / bcrypt-hashed password in `users` table)
2. Navigate to Access Keys → Create
3. Configure scope: "full"
4. Save AK and raw SK to project `.env`:
   ```
   WE_MP_RSS_AK=WKn4pI...
   WE_MP_RSS_SK=SKuv1aZ...
   ```