API docs

Auth

Create a key on your home page and send it on every request: Authorization: Bearer tj_…

GET /api/v1/posts

A subreddit's posts. Params: subreddit (required), sort top|hot|new|rising, time hour|day|week|month|year|all, limit 1–100. Returns { subreddit, sort, posts, bandwidth } in seconds.

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

GET /api/v1/thread

One thread with its full comment tree. Params: url (a full reddit.com permalink, required), limit 1–1,000. Returns { thread, bandwidth } — thread is Reddit's raw listing JSON.

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

POST /api/v1/mine

Scans up to 100 threads, detects questions, flags the unanswered ones, and clusters them by topic. Body: subreddit (required), threads 1–100, time, topic_keywords (regex, optional). Returns 202 with a job to poll, or the result directly with ?wait=1. The result carries { questions, n_unanswered, clusters_unanswered, top_questions, bandwidth }.

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 to hold the request and get the result directly (~30–90s)

GET /api/v1/jobs/{id}

Status and result for a mine. status is queued|running|done|error; result is set when done, error when it failed.

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

Jars — tracked topics and the corpus

A jar tracks a topic in a subreddit — when and how often it gets mined is yours (or your agent's) to decide. Each mine finds threads matching your terms, pulls their full comment trees, and adds only conversations you don't already hold. The corpus is the deliverable — feed it to an LLM and ask for product angles, marketing angles, or content ideas. Create jars on your home page; list them with GET /api/v1/jars.

# harvest whenever you want one (~1 min, holds until done):
curl -s -X POST https://www.trufflejar.com/api/v1/jars/JAR_ID/mine \
  -H "Authorization: Bearer tj_…"

# one paste-ready markdown document of every active conversation:
curl -s "https://www.trufflejar.com/api/v1/jars/JAR_ID/corpus?format=md" \
  -H "Authorization: Bearer tj_…"
# (drop format=md for structured JSON with full comment trees)

# synthesised a thread, or it's noise? retire it — never re-harvested:
curl -s -X POST https://www.trufflejar.com/api/v1/jars/JAR_ID/covered \
  -H "Authorization: Bearer tj_…" -H "Content-Type: application/json" \
  -d '{"permalink": "<from the corpus>", "q": "the thread title", "state": "covered"}'

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.