---
title: "POST /v1/watch"
method: POST
path: "/v1/watch"
tags: ["meta"]
---

# POST /v1/watch

`POST /v1/watch`

## Request

- Base URL: `https://api.pkgseek.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pkgseek.com/v1/watch`
- Auth: one of:
  - API key in header `x-turnstile-token`
  - HTTP bearer

## Request body

- WatchRequest
  - `catalog_revision` string, nullable
  - `distro` string, nullable: Optional distro filter (not honored for abi_exports).
  - `installed` InstalledTarget
    - `source_name` string, nullable
    - `source_version` string, nullable
    - `version` string, required
  - `kind` string, required: Event kind to watch: repository_package_drop, repository_file_drop, abi_exports (global only) or lifecycle.
  - `package` string, nullable
  - `release` string, nullable: Optional release filter (requires distro).
  - `release_policy` string, nullable
  - `schema_version` integer, nullable
  - `scope` PackageScope: An explicit ordinary-repository request uses one exact release snapshot.
    - `arch` string, required
    - `distro` string, required
    - `release` string, required
    - `repo` string, nullable
    - `source` string, required
  - `webhook_url` string, required: HTTPS endpoint, port 443, publicly routable host (verified at registration).

## Response `200`

Webhook watch registered after endpoint verification; secrets returned once

- WatchCreated
  - `catalog_revision` string, nullable
  - `management_token` string, required: Management token for DELETE /v1/watch/{id}, returned exactly once.
  - `policy` string, nullable
  - `schema_version` integer, nullable
  - `signing_secret` string, required: HMAC signing secret (hex), returned exactly once at creation.
  - `subscription` WatchSubscription, required
    - `created_at` string, required
    - `enabled` boolean, required
    - `id` string, required
    - `kind` string, required
    - `target` unknown, required
    - `webhook_url` string, required
  - `verification` WatchVerification, required
    - `detail` string, required
    - `sent` boolean, required
    - `status` integer, nullable

---

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