# OpenAPI specification

The SigWise API is described by an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0)
document. It is the single source of truth for the API contract:

- the [API reference](https://sigwise.ai/docs/reference.md) on this site is rendered from it;
- the [SDKs](https://sigwise.ai/docs/sdks.md) are generated from it;
- the server's test suite fails when a route is added without being described
  in it, so it can't fall behind.

## Download

| Where | |
|-------|---|
| This site | [`/openapi.yaml`](https://sigwise.ai/docs/openapi.yaml) · [`/openapi.json`](https://sigwise.ai/docs/openapi.json) |
| The API itself | `https://api.sigwise.ai/openapi.yaml` · `https://api.sigwise.ai/openapi.json` |
| Source | `api/openapi.yaml` in the repository |

The API serves the specification of the version it runs, so a local server at
`http://localhost:8080/openapi.yaml` always matches your checkout.

## Use it with your tools

- **API clients.** Import the URL into Postman, Insomnia, Bruno or Hoppscotch
  to get every request pre-filled. Requests need a signed token; see
  [Authentication](https://sigwise.ai/docs/guide/authentication.md).
- **Mock servers.** `npx @stoplight/prism-cli mock https://api.sigwise.ai/openapi.yaml`
  serves example responses for offline development.
- **Type generation.** `npx openapi-typescript https://api.sigwise.ai/openapi.yaml -o analyze.d.ts`
  gives you request and response types in any TypeScript project.

## Webhooks

The document also lists the webhooks the API sends (`analysis.completed` and
`rule.triggered`) under `webhooks`, with their payload schemas.