Hep.gg Documentation

AI editing API

Read and write your documentation site programmatically, or let an AI assistant build it: keys, endpoints, and examples.

View as LLM-ready text

AI editing API

Generate or edit an entire doc site programmatically, or hand a key to your AI coding assistant and let it build the site from a single prompt. The API lets a script or an assistant read your current pages and create or replace them.

Keys

There are two kinds, both scoped to a single site:

  • One-off editing key. Starts with dpk_ and expires about an hour after you generate it. Best for a single working session, or to hand to an assistant.
  • Long-lived key. Starts with hepgg_docs_, for scripts and CI.
Authorization: Bearer <KEY>

The authoring guide

If you are pointing an AI assistant at your site, give it the full authoring guide at hep.gg/api/v1/pages/llms. It documents the content model, every component, and this API in one place, so a model can generate a complete site in one pass.

Endpoints

GEThttps://hep.gg/api/v1/pages/ai/siteAuth required
Site summary plus a list of every page (path, title, format). Call this first.
GEThttps://hep.gg/api/v1/pages/ai/pageAuth required
Read one page. Returns path, format, frontmatter, body, and llmBody.
PUThttps://hep.gg/api/v1/pages/ai/pageAuth required
Create or replace a page.
DELETEhttps://hep.gg/api/v1/pages/ai/pageAuth required
Remove a page by path.
POSThttps://hep.gg/api/v1/pages/ai/categoryAuth required
Set a folder's sidebar label, order, and collapsed state.

Writing a page

PUT /ai/page body
path
stringrequired
Where the page lives, with no file extension. Must start with docs/ (a sidebar doc) or pages/ (a standalone page).
format
stringoptionaldefault: mdx
mdx to use components, or md for plain Markdown.
frontmatter
objectoptional
Page metadata: title, description, sidebar_label, sidebar_position, hide_title, draft.
body
stringrequired
The page content in Markdown.
llmBody
stringoptional
An optional plain-Markdown twin of the page for AI agents, served under /llms.

Example

curl
curl -X PUT https://hep.gg/api/v1/pages/ai/page \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "docs/guides/install",
    "format": "mdx",
    "frontmatter": { "title": "Install", "sidebar_position": 2 },
    "body": "# Install\n\nRun the installer."
  }'

Responses

Every response is a JSON envelope:

{ "ok": true, "data": { } }

On failure, ok is false with an error message and a short code:

{ "ok": false, "error": "path must start with docs/ or pages/", "code": "bad_path" }

Organizing the sidebar

Folders become sidebar categories. Set a category's label and order with POST /ai/category:

{ "path": "docs/guides", "label": "Guides", "position": 1, "collapsed": false }

When you are done, publish the site and mount a domain from your dashboard.