POST /v1/watches


Call	`POST /v1/watches`
Price	free to create; each delivered event bills one `score_signal` ($0.005)
Scope	`watches:manage`
Operation id	`createWatch`

What it does

Ask Verdict to push scored events for an ICP to your HTTPS endpoint as they land: each event whose relevant is at least min_p is delivered, signed with Verdict-Signature (see the scoredEvent webhook). The URL must answer the watchChallenge webhook before deliveries start. Creating a watch is free; each delivered event bills one score_signal ($0.005), never per retry. The response includes the signing secret once. Scope: watches:manage.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

curl -X POST 'https://api.askverdict.io/v1/watches' \
  -H "Authorization: Bearer $VERDICT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "icp_id": "icp_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "webhook_url": "https://agent.northwind-ops.io/hooks/verdict",
  "min_p": 0.7,
  "types": [
    "filing",
    "fund_raise",
    "officer_change"
  ]
}'

Example response

201: The watch, pending verification, with its signing secret.

{
  "id": "wch_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "project_id": "prj_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "icp_id": "icp_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "webhook_url": "https://agent.northwind-ops.io/hooks/verdict",
  "min_p": 0.7,
  "types": [
    "filing",
    "fund_raise",
    "officer_change"
  ],
  "status": "pending_verification",
  "created_at": "2026-11-07T14:10:00Z",
  "updated_at": "2026-11-07T14:10:00Z",
  "signing_secret": "whsec_ExampleExampleExampleExampleExample"
}

Parameters

Name	In	Type	Required	Description
`idempotency-key`	header	string (uuid)	yes	A UUID you generate per logical request. Required on every POST. Repeating it within 24 hours returns the stored response and bills nothing; reusing it with a different body returns 409 `idempotency_conflict`.
`x-verdict-version`	header	string	no	API version to use, a date. Defaults to the version current when the key was created. The current version is `2026-11-01`.

Request body

Schema CreateWatchRequest. The watch to create.

Field	Type	Required	Description
`icp_id`	string	yes	Score events for this ICP profile.
`webhook_url`	string (uri)	yes	HTTPS endpoint that receives deliveries. Private and link-local addresses are refused; the URL must answer a challenge at registration.
`min_p`	number	yes	Deliver only events whose `relevant` is at least this.
`types`	array of enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	yes	Event types to watch.

Response fields (201)

Schema CreatedWatch.

Field	Type	Required	Description
`id`	string	yes	The watch id.
`project_id`	string	yes	Project the watch belongs to.
`icp_id`	string	yes	ICP profile events are scored for.
`webhook_url`	string (uri)	yes	Delivery endpoint.
`min_p`	number	yes	Minimum `relevant` delivered.
`types`	array of enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	yes	Event types watched.
`status`	enum: “pending_verification”, “active”, “paused”, “deleted”	yes	Lifecycle status.
`created_at`	string (date-time)	yes	When the watch was created.
`updated_at`	string (date-time)	yes	When the watch last changed.
`signing_secret`	string	yes	Secret for verifying `Verdict-Signature` on deliveries. Shown once; store it now.

Errors

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status	Meaning
`400`	Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (`invalid_request`).
`401`	Missing, malformed, revoked or expired API key, or a bad webhook signature (`unauthorized`).
`403`	The key lacks the scope this operation needs (`forbidden_scope`).
`404`	The resource does not exist in this organization (`not_found`).
`409`	The `Idempotency-Key` was reused with a different request, or the first request is still running (`idempotency_conflict`).
`429`	Rate limited (`rate_limited`). Wait `Retry-After` seconds.
`500`	Unexpected server error (`internal`). Not billed; retry with the same `Idempotency-Key`.

Try it

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.