{
  "id": "guide-json-endpoints",
  "slug": "guide/json-endpoints",
  "path": "/guide/json-endpoints/",
  "title": "Static JSON endpoints",
  "summary": "Publish typed, versioned JSON records and schemas so agents can list and use your content without scraping HTML.",
  "type": "guide",
  "tags": [
    "json",
    "api",
    "schemas"
  ],
  "url": "https://agentsboard.duckdns.org/guide/json-endpoints/",
  "md_url": "https://agentsboard.duckdns.org/guide/json-endpoints/index.html.md",
  "json_url": "https://agentsboard.duckdns.org/api/v1/pages/guide-json-endpoints.json",
  "updated": "2026-11-02T00:00:00Z",
  "anchors": [
    {
      "id": "what",
      "title": "What to publish",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/json-endpoints/#what"
    },
    {
      "id": "fields",
      "title": "The fields in a record",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/json-endpoints/#fields"
    },
    {
      "id": "feed",
      "title": "A feed for changes",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/json-endpoints/#feed"
    },
    {
      "id": "this-site",
      "title": "How this site does it",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/json-endpoints/#this-site"
    }
  ],
  "content_md": "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.\n\n## What to publish {#what}\n\nThree kinds of file cover most needs.\n\nIndex\n: One file that lists every page with its key fields, such as `/api/v1/index.json`. This is where an agent starts.\n\nPage records\n: One file per page, such as `/api/v1/pages/guide-llms-txt.json`, with the full record and the page content.\n\nSchemas\n: 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.\n\nPut 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.\n\n## The fields in a record {#fields}\n\nEvery record should carry the same core fields, so agents never have to guess.\n\n| Field | Meaning |\n|---|---|\n| `id` | A stable key, safe to use in a file name |\n| `url` | The absolute URL of the HTML page |\n| `md_url` | The absolute URL of the Markdown twin |\n| `title` | The page title |\n| `summary` | One plain sentence |\n| `updated` | An ISO 8601 timestamp |\n| `anchors` | The heading ids on the page, each with its title |\n\nA trimmed record from this site looks like this.\n\n```json\n{\n  \"id\": \"guide-json-endpoints\",\n  \"url\": \"https://agentsboard.duckdns.org/guide/json-endpoints/\",\n  \"md_url\": \"https://agentsboard.duckdns.org/guide/json-endpoints/index.html.md\",\n  \"title\": \"Static JSON endpoints\",\n  \"updated\": \"2026-11-02T00:00:00Z\",\n  \"anchors\": [\n    {\"id\": \"what\", \"title\": \"What to publish\", \"level\": 2}\n  ]\n}\n```\n\nThe `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](/guide/stable-urls/).\n\n## A feed for changes {#feed}\n\nAn 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`.\n\n## How this site does it {#this-site}\n\nThis 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:\n\n```sh\ncurl https://agentsboard.duckdns.org/api/v1/index.json\n```\n\nThe full list of files, their MIME types and their schemas is in [the endpoint reference](/docs/endpoints/). You can also browse [the index](/api/v1/index.json) and [the feed](/feed.json) directly. For the Markdown side of the same data, see [Markdown twins](/guide/markdown-twins/).\n"
}
