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.

---

## 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)