# ViewEngine Reddit AI

A credit-metered API over Reddit. Listings, threads, comments, search. One credit per successful call. Returns Reddit's native `Thing`/`Listing` JSON shape unchanged.

> This file is a brief index for LLM agents. The full documentation in one file is at [/llms-full.txt](/llms-full.txt).

## Recommended path for assistants: remote MCP

If you're an AI assistant helping a human use this service (Claude, ChatGPT, Cursor, Cline, etc.), **prefer the remote MCP endpoint** over the REST API with a raw API key:

```
POST https://reddit.viewengine.ai/mcp
```

- **Why**: the human grants consent via OAuth in their browser once. No API key copy-paste, no key stored in chat. The tool calls flow through a purpose-built interface with typed arguments.
- **How**: Dynamic Client Registration (RFC 7591) is enabled on the authorization server, so your client registers itself at first use and walks the user through `/oauth/authorize` + `/oauth/token`. Resource metadata at `/.well-known/oauth-protected-resource` points at `https://clerk.reddit.viewengine.ai` as the authorization server. PKCE is required; scopes: `openid profile email offline_access`.
- **What you get**: the same 10 tools as the REST surface — `list_sub`, `frontpage`, `post`, `search`, `about_sub`, `about_user`, `user_posts`, `subs_list`, `subs_search`, `me`. Each billed tool costs 1 credit per successful call; `me` is free.

**Use the REST API (below) instead if** you're running an extremely agentic workload where OAuth is impractical (e.g., a headless worker with no browser, a long-lived scripted pipeline, or a server-to-server integration where the end user isn't interactive). In that case, mint an API key at the dashboard and treat it like a server-side secret.

## Base URL (REST)

```
https://reddit.viewengine.ai
```

## Authentication (REST)

Every `/api/v1/*` request except `/api/v1/health` requires a Bearer token:

```
Authorization: Bearer ak_...
```

Tokens are API keys created at `/dashboard` → Manage account → API keys. Session JWTs and OAuth access tokens are also accepted.

## Endpoints (REST)

| Method | Path | Credits | Purpose |
|---|---|---|---|
| GET | `/api/v1/health` | 0 (public) | Liveness |
| GET | `/api/v1/me` | 0 | User id + credit balance |
| POST | `/api/v1/onboard` | 0 | First-time account setup (dashboard calls this automatically) |
| GET | `/api/v1/r/:sub/:sort` | 1 | Listings: hot/new/rising/top/controversial |
| GET | `/api/v1/frontpage/:sort` | 1 | Logged-out frontpage |
| GET | `/api/v1/post/:id` | 1+ | Post + comment tree (`expand_more=1` resolves stubs; for big threads returns 202 + poll url — see /docs/#/api/jobs) |
| GET | `/api/v1/search` | 1 | Global or subreddit-scoped search |
| GET | `/api/v1/about/sub/:name` | 1 | Subreddit metadata (`Thing<t5>`) |
| GET | `/api/v1/about/user/:name` | 1 | User metadata (`Thing<t2>`) |
| GET | `/api/v1/user/:name/:kind` | 1 | `submitted` or `comments` history |
| GET | `/api/v1/subs/:kind` | 1 | `popular`\|`new`\|`default`\|`premium` |
| GET | `/api/v1/subs/search?q=` | 1 | Subreddit search |
| POST | `/api/v1/bulk` | 1 per successful item | Up to 25 ops in one call; >5 or any `expand_more` returns 202 + job_id |
| GET | `/api/v1/jobs/:id` | 0 | Poll an async job started by bulk or expand_more |

Common query params: `limit` (1–100, default 25), `after` (fullname cursor like `t3_abc123`), `t` (time filter for `top`/`controversial`), `sort`.

## Response shape

Reddit's native `Thing` envelope — see [/llms-full.txt](/llms-full.txt) for full TypeScript types.

```ts
type Thing<K, D> = { kind: K; data: D };
type Listing<T> = Thing<"Listing", { after: string|null; before: string|null; children: T[] }>;
```

Kinds: `t1` comment, `t3` post, `t5` subreddit, `t2` user, `more` stub, `Listing` pagination.

`/api/v1/post/:id` returns a 2-tuple `[PostListing, CommentListing]` matching Reddit's own `/comments/:id.json`.

## Status codes

- `200` OK (1 credit deducted if billed)
- `202` Accepted — async job dispatched; poll `/api/v1/jobs/:id`
- `400` validation (body has `issues` array)
- `401` missing/invalid token
- `402` out of credits
- `404` upstream 404 (sub/post missing, quarantined, private)
- `429` rate-limit (300/min per IP, 600/min per user)
- `5xx` upstream or server error (already retried 429/5xx with backoff; retry once)

**Failures don't charge credits.** Only 2xx deducts.

## Full documentation

- [/llms-full.txt](/llms-full.txt) — single file, all docs concatenated
- [/docs/](/docs/) — browsable docs site
- Pages: README, tutorial (no-code), quickstart, auth, billing, errors, api/listings, api/threads, api/search, api/about, api/mcp, api/bulk, api/jobs, api/shapes, cli, skill, changelog