# AI & Automation Chronicle Developer Portal

> The public read-only Chronicle API, the OpenAPI specification, markdown content negotiation and the Model Context Protocol endpoint.

Canonical URL: https://chronicle.kcsatish.com/developers

The full archive as JSON, every page as markdown, an OpenAPI 3.1 contract, and a Model Context Protocol endpoint. Read-only, unauthenticated, no key to request.

## 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.json) (OpenAPI 3.1, also available as [YAML](/api/openapi.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](https://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](/.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"}'`
```

**Not affiliated:** the npm package `@chroniclemcp/mcp` is published by an unrelated author and has nothing to do with this publication. This is the only MCP endpoint operated by AI & Automation Chronicle.

## Agent Resources

- [`/llms.txt`](/llms.txt) Site index in the llmstxt.org format: every page and post with a one-line description.
- [`/agent-instructions.md`](/agent-instructions.md) When to use this site, when not to, how to call it, and the full response contract.
- [`/sitemap.xml`](/sitemap.xml) Every indexable URL with a last-modified date.
- [`/robots.txt`](/robots.txt) Crawl policy and sitemap pointer.
- [`/openapi.json`](/openapi.json) OpenAPI 3.1 contract.
- [`/.well-known/mcp`](/.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 →](/contact)