Skip to content

Articles API guide

Status: Live

The reading-detail endpoint is implemented (CSL-230). See API Conventions for auth, errors, and caching.

Orientation for the article endpoints. Swagger (/api/docs/, /api/redoc/) and the Linear ticket hold the exact request and response schemas. This guide covers what each endpoint is and how it behaves, not every field. For the concept, see the Articles overview.

Reading detail: GET /api/articles/{id}/

The single-piece payload behind the article reading screen. It is public, app-key-gated (X-API-Key), user-agnostic, and cacheable (Cache-Control: public + ETag). It returns 404 when the id is not a published article.

How it behaves:

  • kind is "article". The article-specific fields are the contributor byline: subtitle, author (the contributor's display name, or null), and publication_date (an ISO date, or null).
  • No source. Articles are not drawn from a Book, so the payload has no "Discover about the book" block and no Buy CTA. The writing detail has both.
  • No interpretation. The "What This Means" layer is passages-only.
  • Two computed onward rails match the other reading screens (CSL-207). more_on_topic returns Lewis Writings that share the article's theme. related_content returns other Articles that share its tags, with the article itself excluded.
  • No related_quotes. The curated editorial-quotes rail is passage-only, so this payload omits the field instead of returning it empty. See the Passages API guide.
  • Body is Markdown (ADR-0006). Read time comes from its word count. image is the featured_image hero, audio powers the Listen control, and reflection_prompt is the reflect question.

See Swagger for the precise field list and status codes.