Core API Quick Start

This quick start describes the DevDocs flow that the Core API and OpenAPI playground should support. It uses stable product concepts rather than tenant-specific credentials.

What you will model

By the end of this flow, a docs team can:

• connect a source repository
• create a docs site
• generate a preview release
• verify the preview
• promote to production
• attach a readable domain
• add an OpenAPI reference that can be browsed and tested

Step 1 — Create a site

A site represents a reader-facing docs hub.

{
  "name": "Acme Developer Docs",
  "site_key": "acme",
  "source": {
    "provider": "github",
    "repository": "acme/docs",
    "branch": "main",
    "content_root": "docs"
  }
}

DevDocs should return a site identifier, a default preview-safe hostname, and the initial release state.

Step 2 — Request a preview

A preview release lets reviewers inspect a branch before it changes production.

{
  "site_id": "site_acme",
  "branch": "docs/openapi-playground",
  "commit_sha": "abc1234",
  "safe_mode": true
}

The preview should expose a review URL, diagnostics, and enough metadata for proof tooling to confirm what commit is being served.

Step 3 — Verify before promotion

Verification should combine automated checks with browser proof:

• build and type checks pass
• docs routes render
• search and LLM routes respond
• preview metadata matches the intended branch and commit
• browser checks do not show blank pages or framework error overlays

Step 4 — Promote the release

Promotion is the transition from a verified preview to production.

{
  "release_id": "rel_123",
  "promote": true,
  "evidence": {
    "build": "passed",
    "browser": "passed",
    "review": "approved"
  }
}

Production promotion should update release state first, then domain aliases.

Step 5 — Attach an API reference

An API reference links a validated OpenAPI document to generated docs pages and playground configuration.

{
  "site_id": "site_acme",
  "title": "Acme API",
  "spec_url": "https://docs.acme.test/openapi.json",
  "playground": {
    "enabled": true,
    "execution_mode": "safe-demo"
  }
}

The first implementation should use a checked-in DevDocs demo fixture. Real customer imports should come after proxy safety, auth handling, and redaction are in place.