API Endpoints

All API routes are defined across three files: routes/health.ts (public), routes/api.ts (protected, Tier 3), and routes/overview.ts (protected, Tier 1). Protected routes require authentication in production.

Health Check

GET /api/health

Auth: Public (no authentication required)

Response:

{
  "status": "healthy",
  "service": "dochub",
  "version": "1.0.0",
  "uptime": 123.456,
  "database": "connected",
  "environment": "development",
  "timestamp": "2026-02-11T06:00:00.000Z"
}

The database field is determined by running SELECT 1 against the pool. Returns "connected", "disconnected", or "unknown".

Master Manifest

GET /api/manifest

Returns a summary of all projects and their document counts. Designed as the entry point for Claude CLI to discover available documentation.

Response:

{
  "generated_at": "2026-02-11T06:00:00.000Z",
  "projects": [
    {
      "id": "dochub",
      "name": "DocHub",
      "description": "Central documentation platform...",
      "subproject_count": 5,
      "doc_count": 12
    }
  ],
  "total_documents": 12
}

Project Manifest

GET /api/manifest/:project

Returns subprojects within a project.

Response:

{
  "project": { "id": "dochub", "name": "DocHub", "description": "..." },
  "subprojects": [
    { "id": "architecture", "name": "Architecture", "description": "...", "doc_count": 4 },
    { "id": "api", "name": "API Endpoints", "description": "...", "doc_count": 2 }
  ]
}

Errors: 404 if project directory doesn’t exist.

Subproject Manifest

GET /api/manifest/:project/:subproject

The most detailed manifest level. Includes schema coverage booleans and per-document metadata with raw URLs and cross-references.

Response:

{
  "project": "dochub",
  "subproject": { "id": "api", "name": "API Endpoints", "description": "..." },
  "schema_coverage": {
    "purpose": true,
    "architecture": true,
    "variables": false,
    "api_endpoints": true,
    "handshakes": true,
    "data_model": true,
    "dependencies": false,
    "status": true
  },
  "documents": [
    {
      "id": "endpoints",
      "title": "API Endpoints",
      "summary": "Complete reference for all REST API routes...",
      "raw_url": "/api/raw/dochub/api/endpoints",
      "references": [
        { "target": "dochub/architecture", "type": "depends_on" }
      ]
    }
  ]
}

Schema coverage values come directly from _subproject.yaml — they are not auto-detected.

Raw Markdown

GET /api/raw/:project/:subproject/:page

Returns the raw .md file content (including YAML frontmatter) with Content-Type: text/markdown. This is what Claude CLI fetches when it needs the full documentation text.

Errors: 404 if the .md file doesn’t exist.

Individual doc pages also support ?format=raw on the /docs/ routes as an alternative way to get raw markdown.

Search

GET /api/search?q=term

Full-text substring search across all markdown files. Case-insensitive. Minimum query length: 2 characters.

Response:

{
  "query": "MarkdownService",
  "results": [
    {
      "path": "dochub/architecture/services",
      "title": "Service Layer",
      "excerpt": "...Three services do the real work: MarkdownService handles all markdown processing..."
    }
  ]
}

Results are capped at 50. Excerpts are ~150 characters centered on the first match.

Latest Report

GET /api/report/latest

Returns the most recent daily agent report JSON. Reads from the reports/ directory, sorted by filename (date-stamped YYYY-MM-DD.json).

Response: Full AgentReport JSON (see Daily Agent docs for structure).

Errors: Returns { "error": "No reports yet" } if the reports directory doesn’t exist or is empty.

Overview Pages (Tier 1)

GET /overview/

Returns the hub landing page — an HTML page showing all three documentation tiers with navigation cards to each overview page, the docs section, and the API.

GET /overview/:id

Returns a self-contained HTML overview page from content/_overviews/{id}.html. These are visual pages with flow diagrams, architecture maps, and system relationships. They contain embedded CSS and no external dependencies.

Available overview pages:

Errors: 404 if the overview ID is not registered or the HTML file doesn’t exist.

Environment Variables

These variables affect API behavior:

The API routes themselves do not read environment variables directly — they delegate to the service layer which handles configuration.

Dependencies

Internal

External Packages

The manifest and search endpoints rely entirely on the service layer, which in turn uses gray-matter, js-yaml, markdown-it, and glob internally. The API routes themselves have no direct dependency on these packages.