Feedmon HTTPS API Reference

# Feedmon HTTPS API skills

This file is the canonical public reference for Feedmon's HTTPS API.

Use the same origin that serves this document, for example `https://feedmon.example.com` or `http://localhost:8080` during local development.

The JSON file at `/.well-known/mcp.json` is only a small pointer back to this document. If there is ever a mismatch, treat `skills.md` as the source of truth.

---

## Recent posts

### `GET /api/posts/recent`

Returns up to 100 recent posts from the instance's configured feeds as a JSON array.

Supported query parameters:

- `status=all|new`
- `days=<integer>` where `7` is the default and `0` means all time
- `subreddit=<string>`
- `min_score=<integer>`

Each post may include:

- `id`
- `reddit_id`
- `subreddit`
- `title`
- `author`
- `url`
- `permalink`
- `content`
- `published_at`
- `discovered_at`
- `status`
- `feed_name`
- `feed_city`
- `feed_province`
- `comment_count`
- `matched_keywords` when premium matching data is available
- `relevance_score` when premium scoring data is available

`content` is best-effort body text derived from the stored feed item. It may be empty, normalized, HTML-stripped, or truncated. If `content` is empty, use `title`.

---

## Subreddit downloads

### `GET /api/subreddits/{subreddit}/posts/download`

Downloads the locally retained mirror for one configured subreddit as newline-delimited JSON.

Supported query parameters:

- `format=jsonl` optional; JSONL is the only supported format

The response uses `Content-Type: application/x-ndjson` and `Content-Disposition: attachment`.
Each line is one stored post and may include:

- `id`
- `reddit_id`
- `subreddit`
- `title`
- `author`
- `url`
- `permalink`
- `content`
- `published_at`
- `discovered_at`
- `status`
- `is_tracking`
- `created_at`
- `updated_at`
- `matched_keywords` when premium matching data is available
- `relevance_score` when premium scoring data is available
- `scoring_commit_short` when premium scoring data is available

Downloads include all local rows for the subreddit, including archived rows and rows hidden from primary dashboard surfaces. The export is limited to Feedmon's retained local mirror; comments are not included because Feedmon does not currently fetch comment trees.

---

## Ingestion coverage

### `GET /api/ingestion/coverage`

Returns this Feedmon instance's configured subreddit coverage, Valkey stream reachability, retained SQLite mirror state, and a `summary` object.

Important fields:

- `subreddits` is the sorted list of subreddit feeds configured on this Feedmon instance.
- `summary.ok` is `true` when there are no hard `issues`; `warnings` are diagnostic and do not fail coverage.
- `valkey.ping_ok` indicates this instance can reach the shared Valkey used for rfetcher streams.
- `valkey.rfetcher_subs_requested` is the current contents of `rfetcher:subs_requested`, which is only a pending registration handoff queue. Rfetcher may already have registered a subreddit and drained it from this set, so absence here is not proof of lost ingestion.
- `sync` reports retained stream mirror state per subreddit. A missing or behind local mirror is reported as a warning unless the latest sync failed.

Use this endpoint with rfetcher's registered subreddit list or `/rfetcher/api/status` when checking end-to-end ingestion. Do not treat `rfetcher:subs_requested` as durable subscription truth.

---

## Website keyword scan

### `POST /api/settings/keyword-scan`

Scans exactly one public webpage and returns deterministic starter keyword suggestions for Settings Targeting. This is not an exhaustive crawler, does not use an LLM, and does not save keywords automatically. The page can be your own or someone else's.

Send JSON:

```json
{
  "url": "https://example.com"
}
```

Response fields:

- `pages_scanned` and `pages` show the single HTML page that was read.
- `readability` reports an approximate Flesch-Kincaid grade; UI copy should ideally stay around grade 6.
- `important` contains phrase-like suggestions suitable for Important keywords.
- `semi_important` contains additional candidates suitable for Semi-important keywords.
- `warnings` lists non-fatal extraction issues.

Only `http` and `https` URLs are accepted. Private, local, and link-local hosts are blocked by default to avoid server-side request forgery; local development can opt in with `FEEDMON_KEYWORD_SCAN_ALLOW_PRIVATE=1`. Requests are limited to one scan per requester per minute.

---

## Training

### `GET /api/train/posts`

Returns up to 100 unrated training candidates as a JSON array.

Optional query parameters:

- `for_agent=1` to omit `relevance_score`

Notes:

- `matched_keywords`, scoring fields, and keyword-hit metadata are only present when available on the instance
- `content` is optional best-effort text and may be empty

### `POST /api/train/feedback`

Send JSON:

```json
{
  "post_id": 123,
  "rating": "Excellent"
}
```

Accepted ratings:

- `Excellent`
- `Good`
- `Bad`

Ratings are case-insensitive. `Good` is the normal positive-but-not-top rating.

### `POST /api/train/undo`

Send JSON:

```json
{
  "post_id": 123
}
```

This removes the latest feedback for that post.

### `GET /api/train/stats`

Returns training progress JSON. When training stats are not available on the instance, this endpoint may return an empty JSON object.

### Recommended loop

1. `GET /api/train/posts`
2. Choose `Excellent`, `Good`, or `Bad` for a post
3. `POST /api/train/feedback`
4. Optionally `POST /api/train/undo`

---

## Published docs

- Canonical skills document: [`/.well-known/skills.md`](/.well-known/skills.md)
- Human-friendly skills page: [`/docs/skills`](/docs/skills)
- JSON pointer document: [`/.well-known/mcp.json`](/.well-known/mcp.json)
- Human-friendly JSON pointer page: [`/docs/mcp`](/docs/mcp)
- Training UI: [`/train`](/train)
- Posts UI: [`/posts`](/posts)