REST API

The CLI is a thin client for a REST API, and you can call it directly from scripts. Every CLI command has a matching route, with query parameters named after its flags.

curl -s "https://api.scrollhound.com/v1/hn/list?kind=top&limit=5" \
  -H "Authorization: Bearer $SCROLLHOUND_TOKEN"

Auth

Send your token as Authorization: Bearer sh_…. It’s the token value in ~/.config/scrollhound/config.json after scrollhound login. Treat it like a password, and revoke it from the account page.

Format

Responses are JSON by default: { "data": …, "meta": … }, the same as the CLI’s --json (see output format). Add format=md for the compact Markdown the CLI prints, as text/markdown.

Warnings, such as less than 10% of your monthly cap left, come in X-Scrollhound-Warning headers.

Routes

CLI	Route
read <url>	GET /v1/read?url=&comments=&cursor=
transcript <url>	GET /v1/transcript?url=&cursor=
x thread <post>	GET /v1/x/thread?ref=&replies=
x replies <post>	GET /v1/x/replies?ref=&sort=&limit=&cursor=
x quotes <post>	GET /v1/x/quotes?ref=&limit=&cursor=
x article <post>	GET /v1/x/article?ref=&cursor=
x user <handle>	GET /v1/x/user?handle=
x posts <handle>	GET /v1/x/posts?handle=&before=&after=&sort=&replies=true&limit=&cursor=
x search <query>	GET /v1/x/search?q=&since=&min_likes=&lang=&sort=&limit=&cursor=
x trends	GET /v1/x/trends?location=&limit=
yt search <query>	GET /v1/yt/search?q=&since=&sort=&limit=&cursor=
yt video <video>	GET /v1/yt/video?ref=&comments=&cursor=
yt comments <video>	GET /v1/yt/comments?ref=&sort=&q=&limit=&cursor=
yt channel <channel>	GET /v1/yt/channel?ref=&limit=&cursor=
tiktok search <query>	GET /v1/tiktok/search?q=&limit=&cursor=
tiktok user <handle>	GET /v1/tiktok/user?handle=
tiktok videos <handle>	GET /v1/tiktok/videos?handle=&limit=&cursor=
tiktok video <video>	GET /v1/tiktok/video?ref=&comments=&cursor=
tiktok comments <video>	GET /v1/tiktok/comments?ref=&limit=&cursor=
ig search <query>	GET /v1/ig/search?q=&within=&cursor=
ig user <handle>	GET /v1/ig/user?handle=
ig posts <handle>	GET /v1/ig/posts?handle=&limit=&cursor=
ig post <post>	GET /v1/ig/post?ref=&comments=&cursor=
ig comments <post>	GET /v1/ig/comments?ref=&limit=&cursor=
linkedin search <query>	GET /v1/linkedin/search?q=&within=&cursor=
linkedin post <post>	GET /v1/linkedin/post?ref=
linkedin user <profile>	GET /v1/linkedin/user?ref=
linkedin company <company>	GET /v1/linkedin/company?ref=
linkedin posts <owner>	GET /v1/linkedin/posts?ref=&stats=&limit=&cursor=
linkedin ads	GET /v1/linkedin/ads?company=&keyword=&countries=&since=&cursor=
linkedin ad <ad>	GET /v1/linkedin/ad?ref=
hn top (and new, best, ask, show)	GET /v1/hn/list?kind=&limit=&cursor=
hn item <item>	GET /v1/hn/item?ref=&comments=
hn search <query>	GET /v1/hn/search?q=&since=&sort=&limit=&cursor=
reddit sub <name>	GET /v1/reddit/sub?name=
reddit posts <sub>	GET /v1/reddit/posts?sub=&sort=&time=&limit=&cursor=
reddit post <post>	GET /v1/reddit/post?ref=&comments=&sort=
reddit search <query>	GET /v1/reddit/search?q=&sub=&sort=&time=&limit=&cursor=
bookmarks list	GET /v1/bookmarks/list?limit=&cursor=
bookmarks search <query>	GET /v1/bookmarks/search?q=&limit=&cursor=
bookmarks sync [--full]	POST /v1/bookmarks/sync with {"full": true}
usage	GET /v1/usage
whoami	GET /v1/me

Leave out any parameter you don’t need; the defaults and limits are the same as the CLI’s.

Errors

Errors are JSON with an HTTP status:

{ "error": { "code": "not_found", "message": "…", "hint": "…", "requestId": "…" } }

HTTP	Codes
400	invalid_input
401 / 403	unauthenticated, forbidden
404 / 422	not_found, unsupported_url
402	insufficient_credits
409	x_not_connected, x_reauth_required
429	rate_limited, spend_cap_reached, quota_exhausted
500	internal_error
502	upstream_unavailable

The codes mean the same as the CLI’s exit codes.