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:

The four retrieval stages with their corresponding HTTP requests:

1. Discover: Fetch the discovery contract to inspect available endpoints, taxonomy, and query parameters:

   GET /schema.json

2. Filter: Query the index with desired filters and projected fields:

   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:

   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.

Explore documentationSearch and filter the documentationAsk a questionGet an answer from the documentation

Search documentation topics

LanguageEnglishFrançaisAll languages

Information typeAll information typesConceptTaskReference

Structural roleAll page rolesTopicIndexLanding pageOverviewUtility

Loading documentation index…

Copy API query

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 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:

{
  "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

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

2. List task documentation

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

3. Reduce returned fields (token-efficient projection)

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

4. Retrieve a Markdown document

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

5. Paginate through index records

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:

// 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 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
• Glossary