AI & Automation Chronicle Developer Portal

Quickstart

Three requests cover almost every use. Fetch the index, pick a post, fetch the post. No signup, no token, no rate-limit header to parse; the API is static JSON served from the Cloudflare edge.

# 1. Discover the API surface
curl -s https://chronicle.kcsatish.com/api/v1/index.json

# 2. List every post, newest first
curl -s https://chronicle.kcsatish.com/api/v1/posts.json

# 3. Fetch one post, body included, as markdown inside JSON
curl -s https://chronicle.kcsatish.com/api/v1/posts/week-44.json

# Or skip JSON entirely and ask any page for markdown
curl -s -H 'Accept: text/markdown' https://chronicle.kcsatish.com/posts/week-44

API Reference

The machine-readable contract lives at /openapi.json (OpenAPI 3.1, also available as YAML). Every operation has a unique operationId, typed parameters and a response schema, so it can be loaded directly into an LLM function-calling tool definition.

Endpoint	operationId	Returns
GET/api/v1/index.json	getServiceIndex	API version and an absolute URL for every other endpoint.
GET/api/v1/posts.json	listPosts	Every post, newest first: identifier, series, title, summary, tags, reading time, dates, word count, canonical URL, markdown URL.
GET/api/v1/posts/{postId}.json	getPost	One post, plus bodyMarkdown containing the full article including its benchmark tables.
GET/api/v1/stats.json	getStats	Post counts per series, the newest post in each, and every topic tag in use.

Errors

Errors are JSON, never an HTML page. Unknown paths under /api/ return HTTP 404 with a stable machine-readable code and a hint describing the fix. A write method returns HTTP 405 with an Allow header, because the API is read-only.

{
  "error": {
    "status": 404,
    "code": "resource_not_found",
    "message": "No Chronicle API resource is published at /api/v1/authors.",
    "hint": "Read /openapi.json for the full list of endpoints, or start at /api/v1/index.json.",
    "path": "/api/v1/authors",
    "documentation": "https://chronicle.kcsatish.com/developers",
    "specification": "https://chronicle.kcsatish.com/openapi.json"
  }
}

Markdown Content Negotiation

Every page and every post has a markdown twin, following the acceptmarkdown.com convention. Send Accept: text/markdown and the same URL answers with text/markdown; charset=utf-8 instead of HTML. Negotiated responses carry Vary: Accept, Accept-Encoding so a CDN cannot serve the wrong representation.

• Accept: text/markdown returns markdown.
• Appending .md to a path returns markdown without relying on headers, for example /posts/week-44.md.
• Accept: */* or no header returns HTML, because that is what browsers and link unfurlers expect.
• An Accept header that excludes both text/html and text/markdown returns HTTP 406 rather than a surprise representation.
• Every page carries <link rel="alternate" type="text/markdown"> pointing at its markdown twin.

Model Context Protocol

The Chronicle publishes a first-party MCP server so an agent can search and read the archive as tool calls rather than by scraping. The manifest is at /.well-known/mcp and the Streamable HTTP endpoint is /mcp, speaking JSON-RPC 2.0 over POST with no authentication.

Tool	Purpose
list_chronicle_posts	List posts, optionally filtered by series or topic tag.
get_chronicle_post	Fetch one post in full as markdown.
search_chronicle_posts	Full-text search across titles, summaries, tags and bodies, returning the matching sentence for each hit.

# Handshake
curl -s -X POST https://chronicle.kcsatish.com/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'

# List the tools
curl -s -X POST https://chronicle.kcsatish.com/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Agent Resources

• /llms.txt Site index in the llmstxt.org format: every page and post with a one-line description.
• /agent-instructions.md When to use this site, when not to, how to call it, and the full response contract.
• /sitemap.xml Every indexable URL with a last-modified date.
• /robots.txt Crawl policy and sitemap pointer.
• /openapi.json OpenAPI 3.1 contract.
• /.well-known/mcp MCP manifest and endpoint descriptor.

Terms of Use

• Free for any use, commercial included. No key, no quota, no attribution requirement in code.
• Cache for at least one hour. The archive changes once a week; polling more often only costs you latency.
• Send a descriptive User-Agent naming your project so traffic can be told apart from abuse.
• When quoting a post, cite the author, the title and the canonical URL. When quoting a benchmark number from a post, cite the primary source the post names.
• No stability guarantee beyond the published specification. Additive changes ship without notice; a breaking change gets a new path prefix.

Something not working? Report it →