Developers & agents

API documentation

Machine-readable discovery and a small public HTTP API. Most content is HTML pages and RSS — not a commercial API product.

Discovery

OpenAPI 3.1 — full spec at /openapi.json
llms.txt — when to use this site and how agents should call it
API catalog — RFC 9727 linkset
Sitemap — indexable URLs

Public endpoints (no auth)

GET /api/v1/health

curl -sI https://rahulguptadev.in/api/v1/health | grep -i api-version

GET /openapi.json

curl -s https://rahulguptadev.in/openapi.json | head

POST /api/v1/incr

Increment blog post view count. Body: {"slug":"post-slug"}

Unversioned /api/health and /api/incr are stable aliases of v1.

Versioning & deprecation

Current major version is 1. Prefer /api/v1/.... Responses include API-Version: 1.
Breaking changes ship under a new path prefix (e.g. /api/v2/...), not by silently changing v1.
Deprecated endpoints send Deprecation: true and Sunset: <HTTP-date> (RFC 8594) at least 90 days before removal, and are noted here and in OpenAPI.

Authentication

Admin-only routes (image upload, MDX serialize, content mutations) require a Better Auth session via Google OAuth at /admin. Only the site owner's email is allowed. There is no public API key or self-serve signup.

Errors

API errors return application/problem+json with fields type, title, status, code, detail, and optional hint. See the Problem schema in OpenAPI.