---
title: "Add Watch"
method: POST
path: "/monitoring/watches"
tags: ["monitoring"]
---

# Add Watch

`POST /monitoring/watches`

## Request

- Base URL: `https://api.licenscheck.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.licenscheck.com/monitoring/watches`
- Auth: none declared

Watch a contractor: its license and every license linked to it, in any state.

Its current verdict and licenses are recorded as the baseline, so events
report changes from now on. Starting a watch counts as one verification of
the license, as `/verdict` would (once per license per UTC day), since the
response carries its verdict: otherwise watching and unwatching would read
verdicts for free. Watching a license twice under the same `reference`
returns the same watch, at no charge; under a different one it's a separate
watch, so a platform can watch one sub for each of its clients. A key can't
have more watches than its plan includes.

Args:
    body: The license to watch.
    response: The response, for its status code.
    api_key_id: Injected: the caller's key.
    caller: Injected caller, for its plan's watch cap.
    monitoring: Injected `MonitoringRepository`.
    licenses: Injected `LicenseRepository`.
    keys: Injected `ApiKeyRepository`, to count the verification.

Returns:
    The watch.

Raises:
    LicenseNotFoundError: If no license has that ID (a 404).
    HTTPException: 409 when the key is at its plan's watch cap.

## Request body

- WatchIn: Body for POST /monitoring/watches.
  - `license_id` string, uuid, required: Any license of the contractor to watch; every license linked to it is watched too.
  - `reference` string, nullable: Your own label for this watch, e.g. `client-42/sub-981`, returned on the watch and on every event and webhook it produces. The same license under different references is separate watches.

## Response `200`

The key already watches this license; the existing watch.

## Other responses

- `201`: Successful Response
- `401`: No API key, or one that's wrong or revoked.
- `403`: A free key: monitoring needs a paid plan.
- `404`: No license with that ID.
- `409`: The key already has as many watches as its plan includes.
- `422`: Validation Error

---

[API](https://skmtc.dev/licenscheck/apis/licenscheck-api.md) · [All operations](https://skmtc.dev/licenscheck/apis/licenscheck-api/llms.txt) · [OpenAPI document](https://skmtc.dev/licenscheck/apis/licenscheck-api/revisions/472db933f385?raw)