# About this manual's API

## Overview

This manual isn't just an OpenAPI demo somewhere else in the redaction-technique.org family — this site's *own* API is real, and it's already running under every page you're reading. It's a static, zero-runtime endpoint set that mirrors the entire documentation corpus in machine-readable form, for LLMs, AI coding agents, and automated tooling to consume directly, instead of scraping rendered HTML.

Everything below is generated at build time from the same Markdown source as the HTML pages — there's no separate content to keep in sync, and no server-side database or function call involved. It's served as static files from the CDN edge, same as any other asset on this site.

## Why it exists

Rendered HTML is built for browsers: navigation chrome, CSS, client-side interactivity. An LLM or agent that just needs the article text has to strip all of that back out, and can get it wrong. This API skips the round-trip: it serves the same content agents would otherwise reconstruct, as clean Markdown and structured JSON, directly.

## Quick start workflow

The API follows a straightforward, four-stage retrieval pipeline:

```mermaid
%%{init: {"flowchart": {"curve": "basis"}, "themeVariables": {"fontFamily": "IBM Plex Sans Variable, sans-serif"}}}%%
flowchart TD
    accTitle: API Retrieval Pipeline
    accDescr: Sequential four-stage retrieval pipeline: discover contract, query index, select document, and retrieve Markdown.

    A["GET /schema.json"] --> B["Discover endpoints, filters & taxonomy"]
    B --> C["Query document index"]
    C --> D["Select target document"]
    D --> E["Follow advertised markdown URL"]
    E --> F["Retrieve Markdown document"]

    classDef stage fill:#f1f5f9,stroke:#64748b,stroke-width:1.5px,color:#0f172a,font-weight:500
    classDef endpoint fill:#e2e8f0,stroke:#3b82f6,stroke-width:1.5px,color:#1e293b,font-weight:600

    class A,C,F endpoint
    class B,D,E stage

    linkStyle default stroke:#64748b,stroke-width:1.5px
```

The four retrieval stages with their corresponding HTTP requests:

1. **Discover**: Fetch the discovery contract to inspect available endpoints, taxonomy, and query parameters:
   ```bash
   GET /schema.json
   ```
2. **Filter**: Query the index with desired filters and projected fields:
   ```bash
   GET /en/index.json?contentType=task&fields=title,url,markdown,contentType
   ```
3. **Select**: Identify the target document from the results (e.g. `tutorials/auto-insert-data-dita-xml/`) and read its advertised `markdown` property.
4. **Retrieve**: Follow the advertised URL to fetch the clean Markdown source:
   ```bash
   GET /en/tutorials/auto-insert-data-dita-xml.md
   ```

**Discover → Filter → Select → Retrieve**: Consumers discover available capabilities from `/schema.json`, query the index for matching topics, read the advertised Markdown URL, and fetch the clean source text.

## Documentation Explorer

Use the Documentation Explorer to browse the corpus interactively. Each result also exposes the canonical Markdown representation for programmatic and LLM consumption.

## Endpoints

| Endpoint | Format | What it's for |
| --- | --- | --- |
| `/schema.json` | JSON | Machine-readable API discovery contract defining endpoints, query parameters, document schema, and self-describing taxonomy. |
| `/llms.txt` | Plain text | A concise table of contents conforming to the [llms.txt](https://llmstxt.org/) convention — the entry point for an agent that wants to know what's here before fetching anything larger. |
| `/llms-full.txt`, `/llms-full-en.txt`, `/llms-full-fr.txt` | Plain text | The entire corpus (bilingual, or one locale) concatenated into a single file, for an agent that wants to ingest everything in one request instead of one per page. |
| `/index.json`, `/en/index.json`, `/fr/index.json` | JSON | A machine-readable document index: title, description, URL, word count, headings, tags, `pageType`, `contentType`, and taxonomy definitions for every page, with support for query filtering. |
| `/sitemap.md`, `/en/sitemap.md`, `/fr/sitemap.md` | Markdown | A hierarchical sitemap grouped by section, in a format an LLM can read directly rather than parsing an XML sitemap. |
| `/en/<page>.md`, `/fr/<page>.md` | Markdown | A clean Markdown mirror of one page — the same text content as the HTML version, without layout or navigation markup. |

The content under each page's `.md` endpoint is guaranteed byte-for-byte identical to that page's section inside `llms-full.txt` — an automated test in this repository checks that invariant on every build, across every document, not just spot checks.

## Machine discovery via `/schema.json`

Clients, search tools, and LLM/RAG pipelines do not need to hard-code endpoint URLs, query parameters, or classification taxonomies. The `/schema.json` endpoint acts as a **machine-readable API discovery contract**.

From `/schema.json`, an external consumer can discover:

- **Available endpoints**: Global, English, and French index URLs and resource locations (`schema.endpoints`).
- **Supported locales**: `en` and `fr` (`schema.filters.lang`).
- **Information types**: Canonical `contentType` values (`concept`, `task`, `reference`) and human-readable definitions (`schema.taxonomy.contentType`).
- **Structural page types**: Canonical `pageType` values (`topic`, `index`, `landing`, `overview`, `utility`) and definitions (`schema.taxonomy.pageType`).
- **Query parameters**: Supported query keys (`contentType`, `pageType`, `lang`, `fields`, `page`, `limit`), type definitions, defaults, and bounds (`schema.queryParameters`).
- **Document properties**: Canonical record structure (`title`, `url`, `markdown`, `locale`, `pageType`, `contentType`, `wordCount`, `headings`, `keywords`, `tags`) and required fields (`schema.document`).
- **Retrieval model**: Canonical identifier definition (`url`) and representation links (`schema.retrieval`).
- **Pagination rules**: Minimum page (1), limit range (1–100, default 20), and boundary error behavior (`schema.queryParameters`).

## Document metadata and information typing

Every documentation record in the JSON index exposes two complementary classification dimensions:

- **`pageType`**: Describes the structural role of a page in the documentation site (`topic`, `index`, `landing`, `overview`, `utility`).
- **`contentType`**: Describes the primary information type and reader intent (`concept`, `task`, `reference`), or `null` for intentionally untyped pages.

### Semantic distinction

> `pageType` describes the structural role of a page in the documentation site. `contentType` describes the primary information type and reader intent.

For example, a record with:

```json
{
  "pageType": "topic",
  "contentType": "task"
}
```

represents an actionable, task-oriented documentation topic (such as a step-by-step tutorial or procedure).

### Intentionally untyped pages

Organizational and navigational pages — such as section overviews, directory indexes, landing pages, and search utilities — have an explicit structural `pageType` (e.g. `landing`, `overview`, `utility`) but have `contentType: null`. They are intentionally untyped and not forced into Concept, Task, or Reference archetypes.

### Query filtering

The JSON documentation index supports query parameter filtering using an AND operation across dimensions:

| Filter | Example | Description |
| --- | --- | --- |
| Information type | `?contentType=concept` | Returns only conceptual explanations |
| | `?contentType=task` | Returns only step-by-step task articles |
| | `?contentType=reference` | Returns only reference topics |
| Structural page type | `?pageType=topic` | Returns only standard documentation topics |
| | `?pageType=overview` | Returns section overview pages |
| Combined filter | `?pageType=topic&contentType=task` | Returns task-oriented documentation topics satisfying both conditions |
| Locale filter | `?lang=en&contentType=concept` | Returns English concept pages with strict locale isolation |

Invalid parameter values (such as `?contentType=tutorial` or case-mismatched `?contentType=Concept`) return HTTP 400 with a machine-readable payload detailing the allowed canonical values.

## LLM and agent usage

Automated agents, code assistants, and RAG pipelines can consume the site systematically without scraping or heuristic HTML parsing:

1. **Discover capabilities**: Fetch `/schema.json` to inspect endpoints, taxonomy dimensions, and allowed query parameters.
2. **Inspect taxonomy & filters**: Identify appropriate classification keys (e.g. `contentType=task` for procedures, `contentType=concept` for background explanations).
3. **Query index with field projection**: Fetch an index with `fields=title,url,markdown,contentType` to minimize payload size and context token consumption.
4. **Select relevant documents**: Choose documents by URL or title based on the user's inquiry.
5. **Retrieve clean Markdown**: Follow the advertised `markdown` property to retrieve the clean Markdown document.
6. **Ground LLM responses**: Use the unmodified Markdown directly as context.

### Why Markdown for LLM consumers?

- **Clean document representation**: No HTML navigation bars, headers, footers, or client-side script tags polluting the context window.
- **Token efficiency**: Eliminates HTML boilerplate, reserving context window budget for substantive content.
- **Directly consumable**: Headings, lists, code snippets, and tables remain in standard Markdown format.
- **Stable retrieval URL**: Every document advertises its exact Markdown mirror URL in the index metadata.

## Copy-paste `curl` examples

### 1. Discover API and capabilities

```bash
curl https://docs.redaction-technique.org/schema.json
```

### 2. List task documentation

```bash
curl 'https://docs.redaction-technique.org/en/index.json?contentType=task'
```

### 3. Reduce returned fields (token-efficient projection)

```bash
curl 'https://docs.redaction-technique.org/en/index.json?contentType=task&fields=title,url,markdown,contentType'
```

### 4. Retrieve a Markdown document

```bash
curl https://docs.redaction-technique.org/en/tutorials/auto-insert-data-dita-xml.md
```

### 5. Paginate through index records

```bash
curl 'https://docs.redaction-technique.org/en/index.json?contentType=task&page=1&limit=10'
```

## JavaScript consumer example

Here is a minimal, complete example showing how an external consumer or tool can discover, filter, and retrieve content using only the standard `fetch` API:

```javascript
// 1. Fetch the machine-readable discovery contract
const schema = await fetch('https://docs.redaction-technique.org/schema.json')
  .then((res) => res.json());

// 2. Discover the English index endpoint
const enIndexUrl = schema.endpoints.en.index;

// 3. Retrieve English task topics with projected fields
const params = new URLSearchParams({
  contentType: 'task',
  fields: 'title,url,markdown,contentType',
});
const index = await fetch(`${enIndexUrl}?${params}`)
  .then((res) => res.json());

// 4. Select a specific task document
const taskDoc = index.documents.find((doc) =>
  doc.url.includes('auto-insert-data-dita-xml')
);

// 5. Retrieve the clean Markdown representation
const markdown = await fetch(taskDoc.markdown)
  .then((res) => res.text());

console.log(`Retrieved "${taskDoc.title}" (${markdown.length} bytes):`);
console.log(markdown.slice(0, 160));
```

## API stability principles and contract guarantees

The API is treated as stable documentation infrastructure:

- **Canonical `url` as identifier**: The canonical `url` (e.g. `https://docs.redaction-technique.org/en/tutorials/auto-insert-data-dita-xml/`) is the unique, deterministic, and build-stable identifier for every document.
- **Direct Markdown representation**: The `markdown` property always provides the direct, unmodified Markdown mirror for the document, identical byte-for-byte to its section in `llms-full.txt`.
- **Backward compatibility**: Existing unparameterized index responses (`/index.json`, `/en/index.json`, `/fr/index.json`) remain stable and backward-compatible.
- **Canonical taxonomy**: Taxonomy values (`contentType` and `pageType`) are strictly validated against canonical sets. New types are added conservatively and documented symmetrically.
- **Synchronized schema and contract testing**: Any changes to endpoints, taxonomy, or query parameters must update both `/schema.json` and the black-box contract tests (`tests/api-contract.test.mjs`).

## How each page exposes this

You don't need to know these URLs by hand — every page links to its own machine-readable form:

- **`<link rel="alternate">` tags** in the page `<head>` point to the page's `.md` file, the relevant locale index, and `/llms.txt` — discoverable by any tool that reads HTML head metadata, without JavaScript.
- **The "Copy for LLM" button** (visible near the top of every page) copies that page's clean Markdown straight to your clipboard — useful for pasting a page directly into a chat with an AI assistant.
- **The "View as Markdown" link** is a plain `<a>` tag to the `.md` file — works with JavaScript disabled, and is exactly what an agent following the discovery tag would fetch.

## This vs. "Ask the documentation"

This API and the [AI assistant on the homepage](https://docs.redaction-technique.org/en/) solve different problems. The API is for *your own* tools and agents to pull this manual's content into *their* context — a coding agent that wants the docs-as-code article inline while it works, for instance. The homepage assistant is the reverse: it's this site answering a question *for you*, grounded in its own content, with no API key or integration required on your side.

## Related references

- [Explore the reference](https://docs.redaction-technique.org/en/reference/)
- [Glossary](https://docs.redaction-technique.org/en/reference/glossary/)

---

Source: https://docs.redaction-technique.org/en/about-the-api/