Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

File System Watchers

Section titled “File System Watchers”

The file system watcher API lets you create long-running watchers that observe file and directory changes inside a container and deliver events to clients in real time. Use these endpoints to register watchers, inspect their configuration and statistics, replay a recent history of events, or consume a live stream over Server-Sent Events (SSE) or WebSocket.

All endpoints in this section are served from the per-container watch service host:

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

Replace {projectId}, {containerId}, and {server} with the target values for your container.

Health

Section titled “Health”

GET /api/v1/watch/health

Section titled “GET /api/v1/watch/health”

Returns the operational status of the watch service. Use this endpoint to verify that the service is reachable and to inspect runtime information such as the process id, start time, and resource usage.

This endpoint takes no parameters.

Response

Section titled “Response”
{
  "status": "ok",
  "service": "watch",
  "started": "2026-02-11T15:30:00Z",
  "pid": 4821,
  "ip": "10.0.0.12",
  "built": "2026-02-10T12:00:00Z",
  "fds": 64,
  "memory": {
    "rss": 33554432,
    "heap": 16777216
  },
  "userAgent": "HoodyClient/1.0"
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.com/api/v1/watch/health" \
  -H "Authorization: Bearer <token>"

Watchers

Section titled “Watchers”

A watcher is a registered configuration that observes one or more paths and emits events. The endpoints in this section manage the lifecycle of a watcher.

POST /watchers

Section titled “POST /watchers”

Creates a new watcher with the supplied configuration. The watcher begins emitting events as soon as it is created. The body conforms to the watch_CreateWatcherRequest schema; refer to that schema for the authoritative list of supported fields.

This endpoint takes no parameters.

Request body

Section titled “Request body”
{
  "paths": ["/home/user/projects/app/src"],
  "recursive": true,
  "kinds": ["created", "modified", "removed", "renamed"],
  "include": ["**/*.ts"],
  "exclude": ["**/*.test.ts"],
  "ignore_dirs": ["node_modules", ".git"],
  "skip_hidden": true,
  "coalesce_ms": 100,
  "history_size": 1000
}

Response

Section titled “Response”
{
  "id": "c1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-02-11T15:30:00Z",
  "config": {
    "paths": ["/home/user/projects/app/src"],
    "recursive": true,
    "include": ["**/*.ts"],
    "exclude": ["**/*.test.ts"],
    "ignore_dirs": ["node_modules", ".git"],
    "skip_hidden": true,
    "kinds": ["created", "modified", "removed", "renamed"],
    "coalesce_ms": 100,
    "history_size": 1000,
    "history_limit_bytes": 1048576
  },
  "stats": {
    "events_seen": 0,
    "events_broadcast": 0,
    "events_dropped": 0,
    "stream_errors": 0,
    "active_clients": 0
  }
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X POST "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.com/watchers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/home/user/projects/app/src"],
    "recursive": true,
    "kinds": ["created", "modified", "removed", "renamed"],
    "include": ["**/*.ts"],
    "exclude": ["**/*.test.ts"],
    "ignore_dirs": ["node_modules", ".git"],
    "skip_hidden": true,
    "coalesce_ms": 100,
    "history_size": 1000
  }'

GET /watchers

Section titled “GET /watchers”

Returns a paginated list of all watchers registered on the container.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pagequeryintegerNoPage number (1-based).
limitqueryintegerNoItems per page (1-200).

Response

Section titled “Response”
{
  "items": [
    {
      "id": "c1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-02-11T15:30:00Z",
      "config": {
        "paths": ["/home/user/projects/app/src"],
        "recursive": true,
        "include": ["**/*.ts"],
        "exclude": ["**/*.test.ts"],
        "ignore_dirs": ["node_modules", ".git"],
        "skip_hidden": true,
        "kinds": ["created", "modified", "removed", "renamed"],
        "coalesce_ms": 100,
        "history_size": 1000,
        "history_limit_bytes": 1048576
      },
      "stats": {
        "events_seen": 128,
        "events_broadcast": 128,
        "events_dropped": 0,
        "stream_errors": 0,
        "active_clients": 1
      }
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.com/watchers?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

GET /watchers/{id}

Section titled “GET /watchers/{id}”

Returns the configuration, creation timestamp, and runtime statistics for a single watcher.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesWatcher id

Response

Section titled “Response”
{
  "id": "c1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-02-11T15:30:00Z",
  "config": {
    "paths": ["/home/user/projects/app/src"],
    "recursive": true,
    "include": ["**/*.ts"],
    "exclude": ["**/*.test.ts"],
    "ignore_dirs": ["node_modules", ".git"],
    "skip_hidden": true,
    "kinds": ["created", "modified", "removed", "renamed"],
    "coalesce_ms": 100,
    "history_size": 1000,
    "history_limit_bytes": 1048576
  },
  "stats": {
    "events_seen": 128,
    "events_broadcast": 128,
    "events_dropped": 0,
    "stream_errors": 0,
    "active_clients": 1
  }
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.com/watchers/c1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"

DELETE /watchers/{id}

Section titled “DELETE /watchers/{id}”

Stops the watcher and releases its underlying resources. Any active SSE or WebSocket clients connected to the watcher are closed.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesWatcher id

Response

Section titled “Response”
{
  "id": "c1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deleted": true
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X DELETE "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.com/watchers/c1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"

Events and Streams

Section titled “Events and Streams”

These endpoints expose the events a watcher has observed. Use the paginated history endpoint to catch up on missed events, the SSE endpoint for simple streaming, or the WebSocket endpoint for full-duplex communication.

GET /watchers/{id}/events

Section titled “GET /watchers/{id}/events”

Returns a paginated history of events recorded by the watcher. Use since_id or since_timestamp to replay events that occurred after a known point.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesWatcher id
since_idqueryintegerNoReplay events strictly after this event id.
since_timestampquerystringNoReplay 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).
pagequeryintegerNoPage number (1-based).
limitqueryintegerNoItems per page (1-200).

Response

Section titled “Response”
{
  "items": [
    {
      "id": 1,
      "watcher_id": "c1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "kind": "modified",
      "path": "/home/user/projects/app/src/index.ts",
      "timestamp": "2026-02-11T15:31:00Z",
      "is_dir": false,
      "old_size_bytes": 1024,
      "new_size_bytes": 1280,
      "details": null,
      "old_path": null
    },
    {
      "id": 2,
      "watcher_id": "c1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "kind": "created",
      "path": "/home/user/projects/app/src/utils.ts",
      "timestamp": "2026-02-11T15:32:00Z",
      "is_dir": false,
      "old_size_bytes": null,
      "new_size_bytes": 256,
      "details": null,
      "old_path": null
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 2,
  "oldest_available_id": 1,
  "oldest_available_timestamp": "2026-02-11T15:31:00Z",
  "newest_available_id": 2,
  "newest_available_timestamp": "2026-02-11T15:32:00Z"
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.com/watchers/c1b2c3d4-e5f6-7890-abcd-ef1234567890/events?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

GET /watchers/{id}/events/sse

Section titled “GET /watchers/{id}/events/sse”

Opens a Server-Sent Events stream of watcher events. The response is a long-lived text/event-stream connection. Each event is delivered as a JSON payload on the data line. Use since_id or since_timestamp to replay events that occurred after a known point before live streaming begins.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesWatcher id
since_idqueryintegerNoReplay events strictly after this event id.
since_timestampquerystringNoReplay 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).

Response

Section titled “Response”
HTTP/1.1 200 OK
Content-Type: text/event-stream
Connection: keep-alive


data: {"id":1,"watcher_id":"c1b2c3d4-e5f6-7890-abcd-ef1234567890","kind":"modified","path":"/home/user/projects/app/src/index.ts","timestamp":"2026-02-11T15:31:00Z","is_dir":false,"old_size_bytes":1024,"new_size_bytes":1280}


data: {"id":2,"watcher_id":"c1b2c3d4-e5f6-7890-abcd-ef1234567890","kind":"created","path":"/home/user/projects/app/src/utils.ts","timestamp":"2026-02-11T15:32:00Z","is_dir":false,"new_size_bytes":256}

SDK usage

Section titled “SDK usage”
Terminal window
curl -N -X GET "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.com/watchers/c1b2c3d4-e5f6-7890-abcd-ef1234567890/events/sse" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: text/event-stream"

GET /watchers/{id}/events/ws

Section titled “GET /watchers/{id}/events/ws”

Upgrades the HTTP connection to a WebSocket and streams watcher events as text frames containing JSON payloads. Use since_id or since_timestamp to replay events that occurred after a known point before live streaming begins.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesWatcher id
since_idqueryintegerNoReplay events strictly after this event id.
since_timestampquerystringNoReplay 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).

Response

Section titled “Response”
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

SDK usage

Section titled “SDK usage”
Terminal window
curl -N -i \
  -H "Authorization: Bearer <token>" \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  "https://{projectId}-{containerId}-watch-1.{server}.containers.hoody.com/watchers/c1b2c3d4-e5f6-7890-abcd-ef1234567890/events/ws"