# Trufflejar API

The Reddit mining API — posts, threads, and clustered unanswered questions
from any subreddit, as JSON.

Base URL: `https://www.trufflejar.com`
Always call `www` — the apex redirect drops the Authorization header.

## Auth

Create a key at https://www.trufflejar.com/home, then send it on every request:

    Authorization: Bearer tj_…

## GET /api/v1/posts

A subreddit's posts. Returns in seconds.

Query params:
- `subreddit` — required; letters, numbers, underscores
- `sort` — `top` | `hot` | `new` | `rising` (default `top`)
- `time` — `hour` | `day` | `week` | `month` | `year` | `all` (default `month`)
- `limit` — 1–100 (default 30)

    curl -s https://www.trufflejar.com/api/v1/posts \
      -H "Authorization: Bearer tj_…" \
      -G -d subreddit=ClaudeAI -d sort=top -d time=week -d limit=30

Returns `{ subreddit, sort, posts, bandwidth }` — titles, selftext, scores,
permalinks, comment counts.

## GET /api/v1/thread

One thread with its full comment tree.

Query params:
- `url` — required; a full reddit.com thread permalink (`…/r/<sub>/comments/…`)
- `limit` — 1–1,000 comments (default 500)

    curl -s https://www.trufflejar.com/api/v1/thread \
      -H "Authorization: Bearer tj_…" \
      -G --data-urlencode "url=https://www.reddit.com/r/ClaudeAI/comments/…"

Returns `{ thread, bandwidth }` — thread is Reddit's raw listing JSON.

## POST /api/v1/mine

Scans up to 100 threads, detects questions, flags the unanswered ones, and
clusters them by topic. A mine takes ~30–90s.

Body (JSON):
- `subreddit` — required
- `threads` — 1–100 (default 30)
- `time` — as above (default `month`)
- `topic_keywords` — optional regex; only questions matching it count

Default is async — you get a job back immediately:

    curl -s -X POST https://www.trufflejar.com/api/v1/mine \
      -H "Authorization: Bearer tj_…" -H "Content-Type: application/json" \
      -d '{"subreddit": "ClaudeAI", "threads": 30, "time": "month"}'

    → 202 { "job_id": "…", "poll": "/api/v1/jobs/…", "status": "queued" }

Add `?wait=1` (or `"wait": true` in the body) to hold the request and get
`{ job_id, status, result }` directly.

The result: `{ threads_scanned, posts_considered, questions, n_questions,
n_unanswered, clusters_unanswered, top_questions, bandwidth }`.

## GET /api/v1/jobs/{id}

    curl -s https://www.trufflejar.com/api/v1/jobs/JOB_ID \
      -H "Authorization: Bearer tj_…"

Returns `{ id, kind, status, params, result, error, created_at, started_at,
finished_at }` — `status` is `queued` | `running` | `done` | `error`.

## Errors

Non-2xx responses carry `{ "error": "what happened and what to do" }`.
401 is a missing or revoked key, 400 is bad params, 502 means the miner run
failed — a retry usually clears it, since flagged exit IPs rotate on the next
run.

## Fair use

The API is free while we build. Every response includes a `bandwidth` object
with real wire MB, so you can see what your calls cost us.

## Run it locally instead

The miner is open source — bring your own residential proxy and skip the API
entirely: https://github.com/johnkueh/trufflejar-miner. Point your coding
agent at https://www.trufflejar.com/skill.md and it sets everything up.