OpenAPI
Pull BestBlogs curated content, briefs, and reading data into your own workflow or agent through the OpenAPI and CLI.
BestBlogs ships a full OpenAPI plus the official @bestblogs/cli, turning the platform into a content infrastructure your workflows and agents can call.
Three resource families
| Family | Typical use cases | Key endpoints |
|---|---|---|
| Discover | List curated content, fetch topic pages, read briefs / newsletters | /api/v2/resources, /api/v2/topics, /api/v2/brief |
| Read | Pull a single piece, get summaries / translations, trigger the AI Reading Assistant | /api/v2/resources/{id}, /api/v2/copilot/* |
| Capture | Write bookmarks, highlights, reading history | /api/v2/bookmarks, /api/v2/highlights, /api/v2/history |
Three ways to use it
| Layer | Form | For whom |
|---|---|---|
| Direct REST | OpenAPI (HTTP + JSON) | Any language, server-side integrations. See Authentication and Endpoints |
| CLI | @bestblogs/cli shell tool |
Humans, scripts, CI; TypeScript-built, wraps auth, pagination, and retries |
| Agent Skills | @bestblogs/skills SKILL.md bundle |
Claude Code / Codex / Cursor and other agents — 5 skills, 25 primitives, auto-triggered |
All three share the same underlying contract: the CLI shells out to the OpenAPI, and skills shell out to the CLI. Pick the layer that matches your caller — code / human / agent.
Who can call what
| Account | Endpoint scope |
|---|---|
| Free | Basic discover endpoints (curated list, source directory, public brief) |
| Pro | Full v2 (My Brief, For You, AI Reading Assistant, bookmarks / highlights / history) |
The API and CLI both follow the BestBlogs terminology: user-to-source actions are always follow / unfollow; subscribe is reserved for paid relationships.
Next
- Authentication — how to request an OpenAPI key and pass tokens.
- Endpoints — key parameters and sample responses for each family.
- CLI — useful commands once
npm i -g @bestblogs/cliis done. - Agent Skills —
npx @bestblogs/skills installto drop them into Claude Code / Codex.