Overview

The File System Watchers API lets you create per-path watchers that emit real-time file system events. Each watcher maintains an in-memory replay history and supports streaming events to clients over Server-Sent Events (SSE) or WebSocket.

All endpoints are served from a per-container subdomain. The base URL has the form:

https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.icu

Replace {projectId}, {containerId}, and {server} with the appropriate values from your environment before issuing requests.

Health

GET /api/v1/watch/health

Returns service-level health information including process id, startup time, open file descriptors, and memory usage. Useful for readiness checks and monitoring.

cURL

curl -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.icu/api/v1/watch/health" \
  -H "Authorization: Bearer <token>"

SDK

await client.watch.health.check();

Response 200

{
  "status": "ok",
  "service": "watch",
  "started": "2026-02-11T15:30:00Z",
  "pid": 4321,
  "ip": "10.0.0.42",
  "built": "2026-02-10T08:12:33Z",
  "userAgent": "watchd/1.4.2",
  "fds": 128,
  "memory": {
    "rss": 25165824,
    "heap": 8388608
  }
}

Watchers

A watcher is a long-lived configuration that subscribes to one or more filesystem paths and produces events. The endpoints in this section manage watcher lifecycle.

POST /watchers

Creates a new watcher and starts it in the background. The request body describes the paths to monitor and optional filtering or coalescing parameters.

This endpoint takes no path or query parameters.

Request Body

The request body is passed to the SDK as a single object argument.

cURL

curl -X POST "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.icu/watchers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

SDK

await client.watch.watchers.create({ /* body */ });

Response 201

{
  "id": "f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  "created_at": "2026-02-11T15:30:00Z",
  "config": {
    "paths": ["/srv/app/src"],
    "recursive": true,
    "include": [],
    "exclude": [],
    "ignore_dirs": ["node_modules", ".git"],
    "skip_hidden": false,
    "kinds": ["created", "modified", "removed", "renamed"],
    "coalesce_ms": 50,
    "history_size": 10000,
    "history_limit_bytes": 33554432
  },
  "stats": {
    "events_seen": 0,
    "events_broadcast": 0,
    "events_dropped": 0,
    "stream_errors": 0,
    "active_clients": 0
  }
}

Response 400

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

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

Response 409

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

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

Response 500

{
  "code": "WATCHER_START_FAILED",
  "message": "failed to start watcher: ...",
  "details": "inotify_init: too many open files"
}

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

Returns a paginated list of all watchers on the container. Use the page and limit query parameters to control 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 -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.icu/watchers?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

SDK

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

Response 200

{
  "items": [
    {
      "id": "f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
      "created_at": "2026-02-11T15:30:00Z",
      "config": {
        "paths": ["/srv/app/src"],
        "recursive": true,
        "include": [],
        "exclude": [],
        "ignore_dirs": ["node_modules", ".git"],
        "skip_hidden": false,
        "kinds": ["created", "modified", "removed", "renamed"],
        "coalesce_ms": 50,
        "history_size": 10000,
        "history_limit_bytes": 33554432
      },
      "stats": {
        "events_seen": 1240,
        "events_broadcast": 1198,
        "events_dropped": 0,
        "stream_errors": 0,
        "active_clients": 2
      }
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}

Response 400

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

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}

Returns details for a single watcher, including its current configuration and runtime statistics.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Watcher id

cURL

curl -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.icu/watchers/f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" \
  -H "Authorization: Bearer <token>"

SDK

await client.watch.watchers.get('f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c');

Response 200

{
  "id": "f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  "created_at": "2026-02-11T15:30:00Z",
  "config": {
    "paths": ["/srv/app/src"],
    "recursive": true,
    "include": [],
    "exclude": [],
    "ignore_dirs": ["node_modules", ".git"],
    "skip_hidden": false,
    "kinds": ["created", "modified", "removed", "renamed"],
    "coalesce_ms": 50,
    "history_size": 10000,
    "history_limit_bytes": 33554432
  },
  "stats": {
    "events_seen": 1240,
    "events_broadcast": 1198,
    "events_dropped": 0,
    "stream_errors": 0,
    "active_clients": 2
  }
}

Response 404

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

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}

Stops the watcher and removes it. Any active stream clients are disconnected.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Watcher id

cURL

curl -X DELETE "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.icu/watchers/f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" \
  -H "Authorization: Bearer <token>"

SDK

await client.watch.watchers.delete('f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c');

Response 200

{
  "id": "f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  "deleted": true
}

Response 404

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

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 Streams

Once a watcher exists you can read its event history over HTTP, or subscribe to a real-time stream via SSE or WebSocket. All three endpoints accept the same since_id and since_timestamp parameters for replay semantics — events strictly newer than the supplied cursor are returned or delivered.

Tip

For paginated history, page and limit are the standard controls. For continuous streams, omit both since_id and since_timestamp to start from the next live event, or pass them to first replay any retained history and then continue with live events.

GET /watchers/{id}/events

Returns a paginated page of historical events for the watcher. Each item is a watch_FileEvent with a monotonic event id, a kind, and the affected path.

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), or Unix milliseconds (e.g. 1739287800123).
page	query	integer	No	Page number (1-based).
limit	query	integer	No	Items per page (1-200).

cURL

curl -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.icu/watchers/f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/events?page=1&limit=50" \
  -H "Authorization: Bearer <token>"

SDK

await client.watch.streams.listEventsIterator(
  'f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c',
  { page: 1, limit: 50 }
);

Response 200

{
  "items": [
    {
      "id": 1024,
      "watcher_id": "f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
      "kind": "modified",
      "path": "/srv/app/src/index.ts",
      "old_path": null,
      "is_dir": false,
      "timestamp": "2026-02-11T15:32:14.123Z",
      "old_size_bytes": 2048,
      "new_size_bytes": 2150,
      "details": null
    },
    {
      "id": 1025,
      "watcher_id": "f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
      "kind": "created",
      "path": "/srv/app/src/utils/parse.ts",
      "old_path": null,
      "is_dir": false,
      "timestamp": "2026-02-11T15:32:18.401Z",
      "old_size_bytes": null,
      "new_size_bytes": 0,
      "details": null
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 2,
  "oldest_available_id": 1024,
  "oldest_available_timestamp": "2026-02-11T15:32:14.123Z",
  "newest_available_id": 1025,
  "newest_available_timestamp": "2026-02-11T15:32:18.401Z"
}

Response 400

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

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

Response 404

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

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

Response 409

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

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

GET /watchers/{id}/events/sse

Opens a Server-Sent Events stream for the watcher. The connection stays open and pushes new watch_FileEvent payloads as they occur. Optionally pass since_id or since_timestamp to first replay retained history before switching to live delivery.

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), or Unix milliseconds (e.g. 1739287800123).

cURL

curl -N -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.icu/watchers/f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/events/sse" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: text/event-stream"

SDK

await client.watch.streams.streamSse(
  'f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c',
  { since_id: 1024 }
);

Response 200

On a successful response, the server returns 200 OK with Content-Type: text/event-stream and begins streaming events. Each event frame contains a JSON-encoded watch_FileEvent payload in the data field. The connection stays open until the client disconnects or the watcher is deleted.

Response 404

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

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

Response 409

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

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

Response 429

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

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 HTTP connection to a WebSocket and streams events as text frames. As with the SSE endpoint, since_id and since_timestamp can be supplied to replay retained history before live delivery.

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), or Unix milliseconds (e.g. 1739287800123).

cURL

curl -N -i \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.icu/watchers/f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/events/ws?since_id=1024"

SDK

await client.watch.streams.streamWs(
  'f1c2a3b4-5d6e-7f8a-9b0c-1d2e3f4a5b6c',
  { since_id: 1024 }
);

Response 101

On success the server returns 101 Switching Protocols and the connection is upgraded to a WebSocket. Each subsequent text frame contains a JSON-encoded watch_FileEvent payload.

Response 404

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

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

Response 409

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

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

Response 429

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

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