API & Agent Discovery

This page documents the public discovery surface of help.doran.app. It is intended for crawlers, AI agents, and integrators that need to enumerate documentation and consume it in machine-friendly formats.

Discovery resources

• Linkset — /.well-known/linkset (RFC 9264) — lists the canonical entry point for each documentation section.
• API catalog — /.well-known/api-catalog — full JSON manifest of every doc page, grouped by section, with titles, descriptions, and markdown URLs.
• Service docs — every documentation section is advertised via a Link: <…>; rel="service-doc" header on the homepage.

Fetching markdown instead of HTML

Every documentation page is available as plain markdown via two equivalent mechanisms.

Content negotiation (recommended)

Send Accept: text/markdown on any /docs/<slug> request to receive the markdown body of that page instead of the rendered HTML.

curl -H "Accept: text/markdown" https://help.doran.app/docs/account/staff-account

The response uses Content-Type: text/markdown; charset=utf-8 and Cache-Control: private, max-age=3600. Both the HTML and markdown responses are pre-generated at build time, so the markdown endpoint adds no rendering latency.

Dedicated markdown endpoint

The same markdown body is also served at /mdx/<slug> as a stable URL. Use this when you cannot set the Accept header.

curl https://help.doran.app/mdx/account/staff-account

Canonical URL patterns

Documentation sections

Each section's index page is advertised as a service-doc and is enumerated in the API catalog.

• Product Reviews
• Back in Stock & Preorder
• Order Printer
• Shoppable Videos
• Account

Catalog payload

The API catalog is a static JSON document regenerated on every build. Fields:

• site — site name, URL, and description.
• discovery — pointers back to the linkset, catalog, documentation root, and URL patterns.
• content.counts — totals for docs and sections.
• content.sections — one entry per top-level section, with slug, title, url, and docCount.
• content.docs — one entry per documentation page, with slug, title, description, section, url, and markdownUrl.