Reference

Public Content API

API for published posts, journal entries, pages, and lightweight counters. Use explicit endpoints: .json for JSON and .md for markdown. The machine-readable OpenAPI schema lives at /api/openapi.json.

Base URL https://headofengineering.com
OpenAPI /api/openapi.json

Posts

Access published blog posts as structured JSON or raw markdown.

GET /api/posts.json

List posts

View as Markdown

Returns all published posts sorted by publication date descending.

Parameters

This endpoint does not accept parameters.

Returns

A list object with compact post metadata (no full content body).

GET /api/posts/{slug}.json

Retrieve a post

View as Markdown

Returns one post including full markdown content.

Parameters

slug string required
The post slug (for example: the-startup-minded-engineers).

Returns

A post object with metadata and full markdown body.

GET /api/posts/{slug}.md

Retrieve post markdown

View as Markdown

Returns the raw markdown document including frontmatter.

Parameters

slug string required
The post slug.

Returns

A text/markdown response with frontmatter + markdown body.

Journal

Access weekly journal entries in JSON or markdown format.

GET /api/journal.json

List journal entries

View as Markdown

Returns all published journal entries sorted by publication date descending.

Parameters

This endpoint does not accept parameters.

Returns

A list object with journal metadata.

GET /api/journal/{slug}.json

Retrieve a journal entry

View as Markdown

Returns one journal entry with full markdown content.

Parameters

slug string required
The journal slug (for example: 2025-11-16).

Returns

A journal_entry object with metadata and full content.

GET /api/journal/{slug}.md

Retrieve journal markdown

View as Markdown

Returns journal entry markdown including frontmatter.

Parameters

slug string required
The journal slug.

Returns

A text/markdown response with frontmatter + markdown body.

Pages

Access static pages such as About in JSON or markdown format.

GET /api/pages.json

List pages

View as Markdown

Returns all public static pages.

Parameters

This endpoint does not accept parameters.

Returns

A list object with page metadata.

GET /api/pages/{slug}.json

Retrieve a page

View as Markdown

Returns one static page with full markdown content.

Parameters

slug string required
The page slug (for example: about).

Returns

A page object with metadata and full content.

GET /api/pages/{slug}.md

Retrieve page markdown

View as Markdown

Returns raw page markdown including frontmatter.

Parameters

slug string required
The page slug.

Returns

A text/markdown response with frontmatter + markdown body.

Counters

Simple D1-backed counters (used for retro mode visitor counts).

GET /api/counter.json

Read or increment counter

View as Markdown

Returns a key-based counter. By default it increments on each request; use increment=0 for read-only mode.

Parameters

key string
Counter key. Defaults to retro9500:visitors.
increment 0 | 1
Set to 0 to read without incrementing.

Returns

A counter object with numeric count and zero-padded formatted value.

Errors

Unknown API paths return a format-aware 404 response based on what was requested.

Error 404 text/html (static)

Error behavior

Current behavior

  • Known prebuilt endpoints return 200.
  • Unknown .json endpoints return a JSON error object.
  • Unknown .md endpoints return a markdown 404 response.
  • Unknown browser routes (for example /api/does-not-exist) return an API-specific HTML 404 page.

Error types

JSON endpoints use a consistent error shape:

  • not_found: resource is missing (404)
  • invalid_request: malformed input (400), for typed API handlers
  • internal_error: unexpected server error (500), for typed API handlers