---
id: 25
type: docs
title: "Public Content Contract v1"
slug: "public-content-contract-v1"
canonical_url: "https://docs.phatysd.me/content/public-content-contract-v1"
status: published
revision: 2
published_at: "2026-09-19T16:34:11.292Z"
updated_at: "2026-09-19T16:34:11.292Z"
hierarchy_path: "Web Blog > Public Content"
topics:
  - "Content contract"
  - "Agent-readable content"
  - "API design"
tags:
  - "content"
  - "json"
  - "markdown"
  - "llms"
  - "api"
related:
  - slug: "web-blog-agent-handbook"
    title: "Web Blog Agent Handbook"
    type: docs
    canonical_url: "https://docs.phatysd.me/content/web-blog-agent-handbook"
  - slug: "building-agent-readable-knowledge-site"
    title: "Building an Agent-Readable Knowledge Site"
    type: blog
    canonical_url: "https://docs.phatysd.me/content/building-agent-readable-knowledge-site"
---

# Public Content Contract v1

This is the stable contract for published Blog, Docs, and Template content on `docs.phatysd.me`. It is written for agents, integrations, and maintainers who need to discover and consume content without scraping the human UI.

## Content types

| Type | Purpose | Public route |
| --- | --- | --- |
| `blog` | Narrative articles, postmortems, and practical lessons | `/blog` and `/content/:slug` |
| `docs` | Reference, runbook, contract, and how-to material | `/docs` and `/content/:slug` |
| `template` | Structured design template with profile, tokens, and live examples | `/templates` and `/content/:slug` |

The type is part of the published identity. Do not silently change a document into a blog or template without an explicit content revision and metadata review.

## Lifecycle

| Status | Meaning | Publicly indexed? |
| --- | --- | --- |
| `draft` | Work in progress, editable by the owner | No |
| `published` | Current public version | Yes |
| `archived` | Intentionally withdrawn from public discovery | No |

All public queries filter for `status = 'published'`. A draft or archived record must not appear in the homepage, search results, hierarchy pages, sitemap, `llms.txt`, JSON, or Markdown representation.

## Stable URLs

```text
Human canonical page: /content/:slug
Markdown:            /content/:slug/markdown
JSON:                /content/:slug/json
XML discovery:       /sitemap.xml
Agent discovery:     /llms.txt
```

The human page is canonical. The Markdown and JSON representations describe the same published item and must preserve its identity, revision, freshness, and body. A slug is canonical after publication and must not be changed casually; create a deliberate redirect/migration plan if a slug is ever wrong.

## JSON contract

A successful JSON response contains:

```json
{
  "id": 23,
  "type": "docs",
  "title": "Public Content Contract v1",
  "slug": "public-content-contract-v1",
  "canonicalUrl": "https://docs.phatysd.me/content/public-content-contract-v1",
  "status": "published",
  "revision": 1,
  "publishedAt": "2026-09-19T00:00:00.000Z",
  "updatedAt": "2026-09-19T00:00:00.000Z",
  "hierarchyPath": "Web Blog > Public Content",
  "topics": ["Content contract"],
  "tags": ["content", "json"],
  "related": [],
  "body": "# Public Content Contract v1\n..."
}
```

Template items additionally expose validated `templateProfile`, `templateTokens`, and `templateExamples`. A consumer should ignore fields it does not understand and should not infer template semantics from arbitrary CSS.

Missing content returns `404`. Never use `200` with an empty body for a missing slug. Public responses must not expose drafts, archived rows, owner-only fields, database credentials, or internal authorization decisions.

## Markdown contract

Markdown begins with machine-readable front matter containing the same identity fields using snake_case names such as `canonical_url`, `published_at`, `updated_at`, and `revision`. The authored Markdown body follows unchanged. Agents that need a text-first representation should prefer this endpoint over parsing HTML.

## Revision semantics

Publishing a new version increments `revision`. The current row is updated and an immutable row is inserted into `content_revisions`. The revision number is monotonic per content item. Consumers can use it as a freshness signal, but should also compare `updatedAt`.

## Discovery

`llms.txt` is a compact index of published content. `sitemap.xml` is the search-engine-oriented index. Both should contain only canonical public URLs. An agent can start at `https://docs.phatysd.me/llms.txt`, follow a content URL, then choose `/markdown` or `/json` according to the task.

## Source of truth

- Repository sources: `docs/contracts/public-content.md`, `src/lib/agent-content.ts`, and `src/lib/public-content.ts`.
- [Metadata and sitemap conventions](https://nextjs.org/docs/app/api-reference/file-conventions/metadata)
- [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)
