# Quick start

The API is at `https://api.holemonitor.live`. Send your key as `Authorization: Bearer hm_...`. Create keys in the [dashboard](/dashboard/).

## 1. Create an endpoint

```sh
curl -s https://api.holemonitor.live/v1/endpoints \
  -H "Authorization: Bearer $HOLE_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://hooks.example.com/hole-monitor","description":"prod receiver"}'
```

The response includes `secret`, a `whsec_` value. It is shown once. Store it where your receiver reads its secrets.

## 2. Verify the endpoint

A new endpoint is `unverified` and receives nothing but one verification request. That request is signed like any delivery and its body holds a `code`. The endpoint becomes `active` when either:

- your receiver answers the verification request with a 2xx response whose body contains the code, or
- you send the code yourself:

```sh
curl -s https://api.holemonitor.live/v1/endpoints/$ENDPOINT_ID/verify \
  -H "Authorization: Bearer $HOLE_MONITOR_API_KEY" \
  -H "Content-Type: application/json" -d '{"code":"..."}'
```

`POST /v1/endpoints/{id}/verify` with an empty body sends the verification request again, at most 5 times an hour.

## 3. Add a filter

```sh
curl -s https://api.holemonitor.live/v1/endpoints/$ENDPOINT_ID/filters \
  -H "Authorization: Bearer $HOLE_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conditions":{"packages":[{"ecosystem":"npm","name":"next"},{"purl":"pkg:pypi/django"}],"min_cvss":7}}'
```

To keep filters in a repository, `PUT /v1/endpoints/{id}/filters` replaces the whole set from one JSON document. See [Filters](/docs/filters/).

## 4. Send a test event

```sh
curl -s -X POST https://api.holemonitor.live/v1/endpoints/$ENDPOINT_ID/test \
  -H "Authorization: Bearer $HOLE_MONITOR_API_KEY" -H "Content-Type: application/json" -d '{"type":"published"}'
```

The test body has `database_specific.event.test` set to `true`.

## 5. Receive

Verify the signature, reject old timestamps, discard repeated `webhook-id` values and return 2xx quickly. See [Webhooks](/docs/webhooks/) for code, or deploy a [receiver template](/docs/templates/).
