File System Watchers

The Watch API provides programmatic access to file system watchers with real-time event delivery via Server-Sent Events (SSE) and WebSocket streams. Use these endpoints to create watchers that monitor files and directories, retrieve historical events, subscribe to live event streams, and manage watcher lifecycle.

Health

GET /api/v1/watch/health

Returns service health information including process ID, uptime, IP, file descriptor count, and memory usage.

This endpoint takes no parameters.

cURL

curl https://api.example.com/api/v1/watch/health

SDK

const health = await client.watch.health.check();

Response

{
  "status": "ok",
  "service": "watch",
  "started": "2026-02-11T14:00:00Z",
  "pid": 4218,
  "ip": "10.0.1.42",
  "built": "2026-02-10T22:15:00Z",
  "fds": 128,
  "userAgent": "node-watcher/1.2.3",
  "memory": {
    "rss": 67108864,
    "heap": 33554432
  }
}

Watcher Management

POST /watchers

Creates a new file system watcher with the specified paths and configuration.

Request Body

Name	Type	Required	Description
paths	array	Yes	Absolute or relative filesystem paths to watch.
coalesce_ms	integer | null	No	Coalescing window in milliseconds.
exclude	array | null	No	Optional exclude glob patterns. Excludes take precedence over includes.
history_size	integer | null	No	Replay history capacity for this watcher.
ignore_dirs	array | null	No	Directory names or subdirectory paths to skip entirely. Pass empty array to disable the default ignore list.
include	array | null	No	Optional include glob patterns. If present, path must match one include.
kinds	array | null	No	Optional event kind filter. Allowed values: created, modified, removed, renamed, metadata, overflow, other.
recursive	boolean | null	No	Recursive mode. Defaults to server config value.
skip_hidden	boolean | null	No	When true, hidden directories are never watched or scanned into. Defaults to the server’s --default-skip-hidden.

cURL

curl -X POST https://api.example.com/watchers \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/srv/data/uploads", "/srv/data/exports"],
    "recursive": true,
    "kinds": ["created", "modified", "removed", "renamed"],
    "coalesce_ms": 100,
    "history_size": 5000,
    "ignore_dirs": ["node_modules", ".git", "target"],
    "include": ["**/*.csv", "**/*.json"],
    "exclude": ["**/tmp/**"],
    "skip_hidden": true
  }'

SDK

const watcher = await client.watch.watchers.create({
  data: {
    paths: ["/srv/data/uploads", "/srv/data/exports"],
    recursive: true,
    kinds: ["created", "modified", "removed", "renamed"],
    coalesce_ms: 100,
    history_size: 5000,
    ignore_dirs: ["node_modules", ".git", "target"],
    include: ["**/*.csv", "**/*.json"],
    exclude: ["**/tmp/**"],
    skip_hidden: true
  }
});

Response (201)

{
  "id": "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e",
  "created_at": "2026-02-11T15:30:00Z",
  "config": {
    "paths": ["/srv/data/uploads", "/srv/data/exports"],
    "recursive": true,
    "include": ["**/*.csv", "**/*.json"],
    "exclude": ["**/tmp/**"],
    "ignore_dirs": ["node_modules", ".git", "target"],
    "skip_hidden": true,
    "kinds": ["created", "modified", "removed", "renamed"],
    "coalesce_ms": 100,
    "history_size": 5000,
    "history_limit_bytes": 16777216
  },
  "stats": {
    "events_seen": 0,
    "events_broadcast": 0,
    "events_dropped": 0,
    "stream_errors": 0,
    "active_clients": 0
  }
}

400

{
  "code": "INVALID_REQUEST",
  "message": "path list cannot be empty"
}

Error Code	Title	Description	Resolution
INVALID_REQUEST	Invalid request	Request payload failed validation	Check request fields and retry
INVALID_PAGINATION	Invalid pagination	Page or limit is out of range	Use page ≥ 1 and limit between 1 and 200

409

{
  "code": "LIMIT_EXCEEDED",
  "message": "watcher limit reached"
}

Error Code	Title	Description	Resolution
LIMIT_EXCEEDED	Resource limit exceeded	Watcher or path limits exceeded	Reduce paths or delete unused watchers
HISTORY_GAP	Replay history gap	Requested since_id is older than retained replay history	Reconnect without since_id or increase history_memory_limit_bytes

500

{
  "code": "WATCHER_START_FAILED",
  "message": "failed to start watcher: ..."
}

Error Code	Title	Description	Resolution
WATCHER_START_FAILED	Watcher startup failed	Backend failed to initialize file watcher	Check path permissions and kernel watch limits

GET /watchers

Lists all file system watchers with pagination.

Parameters

Name	In	Type	Required	Description
page	query	integer	No	Page number (1-based).
limit	query	integer	No	Items per page (1-200).

cURL

curl "https://api.example.com/watchers?page=1&limit=50"

SDK

const page = await client.watch.watchers.listIterator({
  page: 1,
  limit: 50
});

Response (200)

{
  "items": [
    {
      "id": "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e",
      "created_at": "2026-02-11T15:30:00Z",
      "config": {
        "paths": ["/srv/data/uploads"],
        "recursive": true,
        "include": [],
        "exclude": [],
        "ignore_dirs": ["node_modules", ".git"],
        "skip_hidden": false,
        "kinds": ["created", "modified", "removed", "renamed", "metadata", "overflow", "other"],
        "coalesce_ms": 50,
        "history_size": 1000,
        "history_limit_bytes": 8388608
      },
      "stats": {
        "events_seen": 12480,
        "events_broadcast": 12475,
        "events_dropped": 5,
        "stream_errors": 0,
        "active_clients": 2
      }
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1
}

400

{
  "code": "INVALID_PAGINATION",
  "message": "Limit must be between 1 and 200"
}

Error Code	Title	Description	Resolution
INVALID_REQUEST	Invalid request	Request payload failed validation	Check request fields and retry
INVALID_PAGINATION	Invalid pagination	Page or limit is out of range	Use page ≥ 1 and limit between 1 and 200

GET /watchers/{id}

Retrieves details for a specific watcher.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Watcher id

cURL

curl https://api.example.com/watchers/9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e

SDK

const watcher = await client.watch.watchers.get({
  id: "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e"
});

Response (200)

{
  "id": "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e",
  "created_at": "2026-02-11T15:30:00Z",
  "config": {
    "paths": ["/srv/data/uploads"],
    "recursive": true,
    "include": [],
    "exclude": [],
    "ignore_dirs": ["node_modules", ".git"],
    "skip_hidden": false,
    "kinds": ["created", "modified", "removed", "renamed", "metadata", "overflow", "other"],
    "coalesce_ms": 50,
    "history_size": 1000,
    "history_limit_bytes": 8388608
  },
  "stats": {
    "events_seen": 12480,
    "events_broadcast": 12475,
    "events_dropped": 5,
    "stream_errors": 0,
    "active_clients": 2
  }
}

404

{
  "code": "WATCHER_NOT_FOUND",
  "message": "Watcher not found"
}

Error Code	Title	Description	Resolution
WATCHER_NOT_FOUND	Watcher not found	No watcher exists for provided id	List watchers and use a valid watcher id

DELETE /watchers/{id}

Deletes a watcher and releases its resources.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Watcher id

cURL

curl -X DELETE https://api.example.com/watchers/9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e

SDK

const result = await client.watch.watchers.delete({
  id: "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e"
});

Response (200)

{
  "id": "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e",
  "deleted": true
}

404

{
  "code": "WATCHER_NOT_FOUND",
  "message": "Watcher not found"
}

Error Code	Title	Description	Resolution
WATCHER_NOT_FOUND	Watcher not found	No watcher exists for provided id	List watchers and use a valid watcher id

Event History

GET /watchers/{id}/events

Retrieves paginated historical events for a watcher. Supports replay semantics via since_id or since_timestamp cursors.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Watcher id
since_id	query	integer	No	Replay events strictly after this event id.
since_timestamp	query	string	No	Replay events strictly after this timestamp. Accepted formats: RFC3339 (e.g. 2026-02-11T15:30:00Z), Unix seconds (e.g. 1739287800), Unix milliseconds (e.g. 1739287800123).
page	query	integer	No	Page number (1-based).
limit	query	integer	No	Items per page (1-200).

cURL

curl "https://api.example.com/watchers/9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e/events?since_id=1000&limit=100"

SDK

const events = await client.watch.streams.listEventsIterator({
  id: "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e",
  since_id: 1000,
  limit: 100
});

Response (200)

{
  "items": [
    {
      "id": 1024,
      "watcher_id": "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e",
      "kind": "modified",
      "path": "/srv/data/uploads/report-2026-q1.csv",
      "timestamp": "2026-02-11T15:32:18Z",
      "is_dir": false,
      "old_size_bytes": 4096,
      "new_size_bytes": 8192,
      "old_path": null,
      "details": null
    },
    {
      "id": 1025,
      "watcher_id": "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e",
      "kind": "renamed",
      "path": "/srv/data/uploads/quarterly-final.csv",
      "timestamp": "2026-02-11T15:33:02Z",
      "is_dir": false,
      "old_size_bytes": null,
      "new_size_bytes": null,
      "old_path": "/srv/data/uploads/report-2026-q1.csv",
      "details": null
    }
  ],
  "page": 1,
  "limit": 100,
  "total": 248,
  "oldest_available_id": 1024,
  "newest_available_id": 1271,
  "oldest_available_timestamp": "2026-02-11T15:32:18Z",
  "newest_available_timestamp": "2026-02-11T15:40:11Z"
}

400

{
  "code": "INVALID_PAGINATION",
  "message": "Limit must be between 1 and 200"
}

Error Code	Title	Description	Resolution
INVALID_REQUEST	Invalid request	Request payload failed validation	Check request fields and retry
INVALID_PAGINATION	Invalid pagination	Page or limit is out of range	Use page ≥ 1 and limit between 1 and 200

404

{
  "code": "WATCHER_NOT_FOUND",
  "message": "Watcher not found"
}

Error Code	Title	Description	Resolution
WATCHER_NOT_FOUND	Watcher not found	No watcher exists for provided id	List watchers and use a valid watcher id

409

{
  "code": "HISTORY_GAP",
  "message": "Requested since_id is older than available replay history"
}

Error Code	Title	Description	Resolution
LIMIT_EXCEEDED	Resource limit exceeded	Watcher or path limits exceeded	Reduce paths or delete unused watchers
HISTORY_GAP	Replay history gap	Requested since_id is older than retained replay history	Reconnect without since_id or increase history_memory_limit_bytes

Live Event Streams

GET /watchers/{id}/events/sse

Establishes a Server-Sent Events stream that delivers watcher events in real time. Supports replay from a cursor to recover missed events.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Watcher id
since_id	query	integer	No	Replay events strictly after this event id.
since_timestamp	query	string	No	Replay events strictly after this timestamp. Accepted formats: RFC3339 (e.g. 2026-02-11T15:30:00Z), Unix seconds (e.g. 1739287800), Unix milliseconds (e.g. 1739287800123).

cURL

curl -N "https://api.example.com/watchers/9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e/events/sse?since_id=1000"

SDK

const stream = await client.watch.streams.streamSse({
  id: "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e",
  since_id: 1000
});

for await (const event of stream) {
  console.log(event.kind, event.path);
}

200

SSE stream established. Events are delivered as text/event-stream frames. Each frame contains a data line with a JSON-encoded file event:

id: 1024
event: file_event
data: {"id":1024,"watcher_id":"9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e","kind":"modified","path":"/srv/data/uploads/report.csv","timestamp":"2026-02-11T15:32:18Z","is_dir":false,"old_size_bytes":4096,"new_size_bytes":8192}

404

{
  "code": "WATCHER_NOT_FOUND",
  "message": "Watcher not found"
}

Error Code	Title	Description	Resolution
WATCHER_NOT_FOUND	Watcher not found	No watcher exists for provided id	List watchers and use a valid watcher id

409

{
  "code": "HISTORY_GAP",
  "message": "Requested since_id is older than available replay history"
}

Error Code	Title	Description	Resolution
LIMIT_EXCEEDED	Resource limit exceeded	Watcher or path limits exceeded	Reduce paths or delete unused watchers
HISTORY_GAP	Replay history gap	Requested since_id is older than retained replay history	Reconnect without since_id or increase history_memory_limit_bytes

429

{
  "code": "MAX_CLIENTS_REACHED",
  "message": "Watcher has reached max stream clients"
}

Error Code	Title	Description	Resolution
MAX_CLIENTS_REACHED	Too many clients	Watcher stream client limit reached	Disconnect idle clients or increase max_clients_per_watcher

GET /watchers/{id}/events/ws

Upgrades the connection to a WebSocket and streams file events as text frames. Supports replay from a cursor.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Watcher id
since_id	query	integer	No	Replay events strictly after this event id.
since_timestamp	query	string	No	Replay events strictly after this timestamp. Accepted formats: RFC3339 (e.g. 2026-02-11T15:30:00Z), Unix seconds (e.g. 1739287800), Unix milliseconds (e.g. 1739287800123).

cURL

curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  "https://api.example.com/watchers/9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e/events/ws?since_id=1000"

SDK

const socket = await client.watch.streams.streamWs({
  id: "9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e",
  since_id: 1000
});

socket.on("message", (frame) => {
  const event = JSON.parse(frame.toString());
  console.log(event.kind, event.path);
});

101

WebSocket connection upgraded. Subsequent frames contain JSON-encoded file events:

{"id":1024,"watcher_id":"9b2e7a10-1f4d-4b8a-9c1e-2a0f8c3b4d5e","kind":"modified","path":"/srv/data/uploads/report.csv","timestamp":"2026-02-11T15:32:18Z","is_dir":false,"old_size_bytes":4096,"new_size_bytes":8192}

404

{
  "code": "WATCHER_NOT_FOUND",
  "message": "Watcher not found"
}

Error Code	Title	Description	Resolution
WATCHER_NOT_FOUND	Watcher not found	No watcher exists for provided id	List watchers and use a valid watcher id

409

{
  "code": "HISTORY_GAP",
  "message": "Requested since_id is older than available replay history"
}

Error Code	Title	Description	Resolution
LIMIT_EXCEEDED	Resource limit exceeded	Watcher or path limits exceeded	Reduce paths or delete unused watchers
HISTORY_GAP	Replay history gap	Requested since_id is older than retained replay history	Reconnect without since_id or increase history_memory_limit_bytes

429

{
  "code": "MAX_CLIENTS_REACHED",
  "message": "Watcher has reached max stream clients"
}

Error Code	Title	Description	Resolution
MAX_CLIENTS_REACHED	Too many clients	Watcher stream client limit reached	Disconnect idle clients or increase max_clients_per_watcher

Note

Reconnect with since_id to replay events after the last seen id. If the requested cursor is older than the retained history buffer, the server returns HISTORY_GAP. In that case, reconnect without a cursor or increase history_memory_limit_bytes.