---
title: Hep.gg Docs AI editing API (LLM)
description: HTTP API to read and write the pages of a Hep.gg documentation site, for scripts and AI assistants.
---

# Hep.gg Docs AI editing API

Read and write the pages of one Hep.gg documentation site programmatically.

Base URL: https://hep.gg/api/v1/pages
Auth: Authorization: Bearer <KEY>
Keys (scoped to one site, created in the editor API & AI tab):
- dpk_... one-off, expires ~1 hour. For a single session or an assistant.
- hepgg_docs_... long-lived, for scripts/CI.
Full authoring guide (content model + every component + this API):
https://hep.gg/api/v1/pages/llms

## Envelope
Success: { "ok": true, "data": ... }
Failure: { "ok": false, "error": "message", "code": "short_code" }

## Endpoints
GET /ai/site
  -> data: site summary + every page (path, title, format). Call first.
GET /ai/page?path=docs/guides/install
  -> data: { path, format, frontmatter, body, llmBody }
PUT /ai/page  (JSON)
  body: {
    path,         // required, starts with docs/ or pages/, no extension
    format,       // "mdx" (default) or "md"
    frontmatter,  // { title, description, sidebar_label, sidebar_position, hide_title, draft }
    body,         // required, Markdown
    llmBody       // optional plain-Markdown twin, served under /llms
  }
  -> creates or replaces the page.
DELETE /ai/page?path=docs/guides/old
  -> removes the page.
POST /ai/category  (JSON)
  body: { path, label, position, collapsed }
  -> sets a folder's sidebar label/order/collapsed.

## Content model
- Doc page path docs/<folder>/<name> serves at /docs/<folder>/<name>. First
  segment always docs. Folders become sidebar categories.
- Standalone page path pages/<name> serves at /<name>.
- Sidebar order from frontmatter sidebar_position (lower = higher); category
  label/order via POST /ai/category.
- format mdx (components) or md (plain CommonMark + GFM). Raw HTML/script,
  imports, exports, and {expression} braces are stripped.

## Example
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."}'