# Share a Spectral Report — API Style Findings as a Link

Canonical: https://commareports.com/share-spectral-report
Published: 2026-09-15

> Spectral has a built-in HTML formatter, so an OpenAPI linting run is already a page. Publish it to Comma and the API guild can comment on the rules instead of arguing in a channel.

# Share a Spectral report

An API style guide is a policy document that nobody reads until it blocks
them. Spectral turns it into findings, which is a big improvement — and then
prints those findings into a CI log, which is not.

Unlike most linters, Spectral will hand you a page directly.

## One command, one page

```bash
npm i -D @stoplight/spectral-cli

npx spectral lint openapi.yaml \
  --ruleset .spectral.yaml \
  --format html \
  --output spectral.html || true
```

No converter, no SARIF hop. `--format html` is built in.

## Publish it

Drag `spectral.html` into [the app](https://commareports.com/), or from CI:

```bash
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 spectral.html \
        --arg title "API style — $GITHUB_REF_NAME" '{title: $title, html: $html}')"
```

Keep a separate `spectral lint --fail-severity=error` step if you want the
gate; the reporting step should publish warnings too.

## Style rules are a negotiation

This is the report type where commenting earns its keep. Every Spectral
finding is one of two things: a spec that should change, or a rule that
should. Both are arguments, and arguments need a shared surface.

- **Anchored threads** on the violation — "operationId casing: we inherited
  snake_case from the old gateway, exempting v1" — so the exemption lives next
  to the finding rather than as a `spectral.yaml` override with no context.
  See [commenting on HTML](/comment-on-html).
- **Revisions**, so a ruleset tightening is a diff, and the spec owner can see
  what a new rule would have flagged before it is enforced.
- **Access per report** — public if the spec is public, team-scoped if it
  isn't. See the [sharing model](/docs/sharing).

## Limits

- **Entry HTML: 5 MB.** Assets: 25 MB per file, 250 MB and 500 files total.
- **60 requests/minute per token.**

## Try it

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

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

### Related

- [Share OpenAPI docs](/share-openapi-docs) · [Share Redoc API docs](/share-redoc-api-docs)
- [Share Scalar API docs](/share-scalar-api-docs) · [Share AsyncAPI docs](/share-asyncapi-docs)
- [Share a Schemathesis report](/share-schemathesis-report) · [Publish from CI](/docs/ci)