---
title: "Create a watch (free)"
method: POST
path: "/api/v1/watch"
tags: ["Watch"]
---

# Create a watch (free)

`POST /api/v1/watch`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/watch`
- Auth: HTTP bearer

Create a watch tied to your credit token: a filter over parcels/geography + change event types. It reports changes going FORWARD; poll it to receive (and pay per delta for) new changes. Managing watches is free. Body: { filter, event_types?, name? } where filter is { parcel_ids:[...] } | { canonical_ids:[...] } | { state_fips } | { county_fips, state_fips } and event_types is a subset of parcel.sold / parcel.owner_changed / parcel.permit_filed (default all). Parcel ids (1–500) are canonical `state_fips:county_fips:parcel_id` ids, parcel UUIDs, or bare parcel_ids that name exactly ONE served parcel; a bare id that names several parcels is refused (422, candidates listed). The watch is stored and matched on canonical ids; `parcel_resolution` reports how each input resolved.

## Headers

- `X-CREDIT-TOKEN` string, required

## Request body

- object
  - `name` string
  - `event_types` string[]: Default: all three.
  - `filter` object, required: Exactly one shape: `{parcel_ids: [...]}` / `{canonical_ids: [...]}` (1-500 ids), `{state_fips}` or `{state_fips, county_fips}`.
    - `parcel_ids` string[]
    - `canonical_ids` string[]
    - `state_fips` string
    - `county_fips` string

## Response `200`

Watch created.

- object

## Other responses

- `400`: Invalid filter/event_types.
- `401`: Missing/invalid credit token.
- `405`: The endpoint exists but does not support this method. `Allow` lists the methods it does.
- `422`: One or more parcel ids do not name exactly one parcel (problem+json, `code: parcel_identity_unresolved`, `issues[]` with per-input reason codes and candidate canonical ids). Nothing was created.
- `500`: Unexpected server error. The body never carries database or driver text.

---

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