---
title: "Send a test delivery"
method: POST
path: "/api/v1/watches/{watch_id}/test"
tags: ["Board Watches"]
---

# Send a test delivery

`POST /api/v1/watches/{watch_id}/test`

## Request

- Base URL: `https://api.vaquill.ai`
- URL: `https://api.vaquill.ai/api/v1/watches/{watch_id}/test`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/vaquill/apis/vaquill-developer-api/docs/api/v1/watches/:watch_id/test/post.ts> (a function with typed inputs; its response is checked against the schema)

Fire a one-off test delivery for a watch you own, so you can verify your webhook endpoint or email address before relying on it for real notifications. Sent with `X-Vaquill-Event: board.test` so your handler can tell it apart from a real `board.updated` event. Not persisted to delivery history and does not affect the watch's real last-notified state. Limited to one test send per watch every 30 seconds.

Free.

## Path parameters

- `watch_id` string, required: Id of the watch, as returned by `POST /watches` (`id`).

## Response `200`

Test delivery attempted (check `data` for per-channel outcome).

- WatchTestEnvelope
  - `data` object, required: The outcome of the test delivery.
  - `meta` ResponseMeta, required: The `meta` block every board-watch route returns beside `data`.
    - `processingTimeMs` number, required
    - `creditsConsumed` number, required
    - `cursor` integer, nullable: Change feeds only: the value to send back as `sinceId`. Null on an empty page. The highest change `id` on the page, except on a full newest-first page read with a `sinceId`, where unread rows sit below the page and the cursor stays at your `sinceId`; use `nextBeforeId` to reach them.
    - `nextBeforeId` integer, nullable: Change feeds only, full `order=desc` pages: the lowest change `id` on the page. Send it as `beforeId` for the next older page. Null otherwise.
    - `hasMore` boolean, nullable: Change feeds only: true when the page filled to `limit`.

## Other responses

- `401`: Invalid or missing API key.
- `404`: Watch not found.
- `422`: Validation error: `detail` plus one `errors` entry per rejected field.
- `429`: Rate limit exceeded, or a test delivery was already sent for this watch within the cooldown window (`Retry-After` says when to retry).
- `500`: Internal error (`internal_error`, retryable). Any credits charged for the call are refunded; retry with backoff and quote `requestId` to support if it persists.

## Changes

- **2026-11-07** `340c0d24d0b6`: 38 info
  - added the non-success response with the status `500`
  - added the optional property `candidateCount` to the response with the `401` status
  - added the optional property `candidateCount` to the response with the `404` status
  - added the optional property `candidateCount` to the response with the `422` status
  - …34 more

[Operation history](https://skmtc.dev/vaquill/apis/vaquill-developer-api/changes/api/v1/watches/:watch_id/test/post.md)

---

[API](https://skmtc.dev/vaquill/apis/vaquill-developer-api.md) - [All operations](https://skmtc.dev/vaquill/apis/vaquill-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vaquill/apis/vaquill-developer-api/revisions/340c0d24d0b6?raw)