# Share Scalar API Docs — One HTML File From Your OpenAPI Spec

Canonical: https://commareports.com/share-scalar-api-docs
Published: 2026-09-12

> Scalar renders an OpenAPI spec into a modern reference page. Publish the standalone HTML to Comma so reviewers can read the endpoints and comment on the ones that are wrong.

# Share Scalar API docs

An API reference is the one document where a wrong line has a support ticket
attached to it. Which is why it should be reviewed by the people who implement
the endpoints — and why the reference usually reaches them as a link to a spec
file on a branch.

## Render the reference to one file

```html
<!-- scalar.html -->
<!doctype html>
<html>
  <body>
    <script id="api-reference" type="application/json">
      <!-- your OpenAPI document, inlined -->
    </script>
    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
  </body>
</html>
```

Inline the spec into the `<script type="application/json">` block rather than
pointing Scalar at a URL. A reference page that fetches its own spec is a page
that renders empty for anyone outside your network — the
[self-contained HTML](/glossary/self-contained-html) rule applies here as much
as to a chart.

Generate it in the job that already validates the spec:

```bash
jq -c . openapi.json > /tmp/spec.json
python - <<'PY' > scalar.html
import json, pathlib
spec = pathlib.Path("/tmp/spec.json").read_text()
tpl = pathlib.Path("scalar.template.html").read_text()
print(tpl.replace("<!-- SPEC -->", spec))
PY

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html scalar.html \
        --arg title "API reference — $GIT_SHA" '{title: $title, html: $html}')"
```

## Why review beats "read the spec"

- **Anchored threads** — "this field is required in practice" sits on the
  endpoint. See [commenting on HTML](/comment-on-html).
- **Revisions at one URL** — one report id for the reference; each spec change
  appends a revision, so a reviewer can see what moved.
- **Access per report** — unlisted for a partner, domain-gated for a
  customer's org, team-only pre-launch. See the [sharing model](/docs/sharing).

## Limits

- **Entry HTML: 5 MB.** A large inlined spec plus the renderer can approach
  it; split by tag, or attach the spec as an asset and accept the fetch.
- **Assets: 25 MB per file, 250 MB and 500 files per report.**
- **60 requests/minute per token.**

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision
history.

**[Publish an API reference →](https://commareports.com/)**

### Related

- [Share OpenAPI docs](/share-openapi-docs) · [Share Swagger UI docs](/share-swagger-ui-docs)
- [Share Redoc API docs](/share-redoc-api-docs) · [Share a Mintlify docs site](/share-mintlify-docs)
- [Share a Starlight docs site](/share-starlight-docs) · [For technical writers](/for/technical-writers)
