Static JSON endpoints
Publish typed, versioned JSON records and schemas so agents can list and use your content without scraping HTML.
Markdown is good for reading. JSON is good for working with data. An agent that wants to list every page, filter by tag, or check what changed since yesterday should not have to scrape HTML to do it. A small set of static JSON files gives it a typed, predictable API, and it needs no server code at all.
What to publish
Three kinds of file cover most needs.
- Index
- One file that lists every page with its key fields, such as
/api/v1/index.json. This is where an agent starts. - Page records
- One file per page, such as
/api/v1/pages/guide-llms-txt.json, with the full record and the page content. - Schemas
- A JSON Schema for each record type, such as
/api/v1/schema/page.schema.json, so an agent or its builder can check the shape.
Put the version in the path. If the format ever has to change in a way that breaks clients, publish /api/v2/ next to the old one instead of changing /api/v1/ under people's feet.
The fields in a record
Every record should carry the same core fields, so agents never have to guess.
| Field | Meaning |
|---|---|
id | A stable key, safe to use in a file name |
url | The absolute URL of the HTML page |
md_url | The absolute URL of the Markdown twin |
title | The page title |
summary | One plain sentence |
updated | An ISO 8601 timestamp |
anchors | The heading ids on the page, each with its title |
A trimmed record from this site looks like this.
{
"id": "guide-json-endpoints",
"url": "https://agentsboard.duckdns.org/guide/json-endpoints/",
"md_url": "https://agentsboard.duckdns.org/guide/json-endpoints/index.html.md",
"title": "Static JSON endpoints",
"updated": "2026-11-02T00:00:00Z",
"anchors": [
{"id": "what", "title": "What to publish", "level": 2}
]
}
The anchors list ties the data back to the page. An agent can build a deep link to any section from url plus an id, and the ids never change, as explained in Stable URLs and anchors.
A feed for changes
An agent that wants to stay up to date should not have to download every record each day. A JSON Feed 1.1 file at /feed.json lists recent items with their dates, so the agent can poll one small file and fetch only what changed. Each item carries an id, a url, a title and a date_modified.
How this site does it
This site writes all of its JSON at build time, from the same source files as the HTML and Markdown, so the three cannot disagree. The page id is the URL path with slashes turned into hyphens, so /guide/json-endpoints/ becomes guide-json-endpoints. You can fetch the index with:
curl https://agentsboard.duckdns.org/api/v1/index.json
The full list of files, their MIME types and their schemas is in the endpoint reference. You can also browse the index and the feed directly. For the Markdown side of the same data, see Markdown twins.