Endpoints

The full OpenAPI schema is at https://bestblogs.dev/api/v2/openapi.json. This page lists the most used calls.

Discover

GET /api/v2/resources — list curated content

Returns items that passed AI Screening + Expert Review.

Param	Type	Notes
type	string	article / podcast / video / tweet / newsletter
category	string	Category slug, e.g. ai-engineering
language	string	zh / en / all
time	string	24h / 3d / 1w / 1m / all
qualified	boolean	true returns Featured only
score	string	e.g. 80+
limit	int	Default 20, max 100
cursor	string	Pagination cursor

GET /api/v2/topics — list Topic pages

curl https://bestblogs.dev/api/v2/topics?type=event&limit=10 \
  -H "Authorization: Bearer $KEY"

GET /api/v2/brief?date=YYYY-MM-DD — fetch a specific day's brief

Param	Notes
date	Defaults to today, YYYY-MM-DD format (no Sunday edition)
flavor	public (default) / personal (Pro, requires read:personal scope)

GET /api/v2/sources — public source directory

Supports category / language / type filters; paginates the same way.

Read

GET /api/v2/resources/{id} — single item detail

Returns full body + AI summary + key arguments + tags.

POST /api/v2/copilot/summary — request an AI summary

{
  "resourceId": "art_123",
  "style": "key_points"  // key_points / quotes / socratic
}

Returns a structured summary with cited paragraphs.

POST /api/v2/copilot/ask — follow-up Q&A

{
  "resourceId": "art_123",
  "question": "What agent architecture does the author recommend?"
}

Capture (writes)

Requires write:capture scope.

POST /api/v2/bookmarks

{
  "resourceId": "art_123",
  "folderId": "fld_inbox",
  "tags": ["to-write", "inspiration"],
  "note": "Contrast with Mastra's Workflow model"
}

POST /api/v2/highlights

{
  "resourceId": "art_123",
  "text": "AI handles volume, experts handle quality.",
  "comment": "Core mechanism of BestBlogs",
  "anchor": { "selector": "p:nth-child(7)" }
}

POST /api/v2/history — report a read

Called by agents or third-party readers after the user actually reads.

{
  "resourceId": "art_123",
  "durationMs": 240000,
  "completedAt": "2026-04-26T08:30:00Z"
}

Common response shape

All endpoints return:

{
  "data": [/* resource array */],
  "pagination": {
    "nextCursor": "eyJ...",
    "hasMore": true
  },
  "meta": {
    "total": 1234,
    "requestId": "req_abc"
  }
}

Errors:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retryAfterSec": 12
  }
}