Engagement API

This site runs a small public API that keeps per-article view and like counters. It is anonymous, requires no authentication and no account, and is documented here so both people and AI agents can integrate against something real instead of guessing.

Base URL

https://blog-engagement.ofers.workers.dev (Cloudflare Workers). The machine-readable contract is the OpenAPI specification at /openapi.json.

Rules that apply to every request

• Send the header Origin: https://ofershap.github.io. Other origins get 403.
• key is the article path exactly as served here, for example /posts/agent-long-creative-build-feedback/. Unknown paths are rejected.
• client is a random 32-character lowercase hex id your client generates once and reuses; it deduplicates views and likes. No personal data is stored: IPs are salted and hashed for rate limiting only.
• Rate limit: 30 requests per minute per IP, then 429.
• All errors are JSON: {"error": "..."} with status codes 400, 403, 404, 405, 413 or 429.

GET /health

Liveness check, no parameters.

curl https://blog-engagement.ofers.workers.dev/health
{"ok":true,"version":"1","counting_since":"2026-10-07"}

GET /stats

Read counters for one article.

curl -H "Origin: https://ofershap.github.io" \
  "https://blog-engagement.ofers.workers.dev/stats?key=/posts/agent-long-creative-build-feedback/&client=0123456789abcdef0123456789abcdef"
{"likes":0,"liked":false}

The views field appears only after an article passes the public view threshold; below it the field is omitted on purpose.

POST /stats

Record one engagement. Body is JSON with key, client and action (one of view, like, unlike).

curl -X POST -H "Origin: https://ofershap.github.io" -H "Content-Type: application/json" \
  -d '{"key":"/posts/agent-long-creative-build-feedback/","client":"0123456789abcdef0123456789abcdef","action":"like"}' \
  https://blog-engagement.ofers.workers.dev/stats
{"likes":1,"liked":true}

A view counts once per client per day; a like is idempotent per client and can be withdrawn with unlike.

Scope

These are the only public endpoints. There is no public write access to content, no admin API and no authenticated surface to document; what is not listed here does not exist publicly.