DonutworkHelp Center
Api ReferenceSystems & Monitoring
Donutwork documentation

Directory Monitor

High-performance filesystem monitoring and event synchronization for distributed projects.

Directory Monitor

The Directory Monitor API enables real-time synchronization and event orchestration for local filesystem changes. It is designed for deep integration with local agents to monitor project directories, capture file events, and trigger remote workflows.

Initialize Monitor (Startup)

Signal the start of a monitoring session for a specific project. This initialization step validates the project configuration and prepares the environment for ingress events.

POST
/2026-02-01/directory-monitor/{projectId}.json
Required permissiondirectory_monitor:write

Path, query, and header parameters

projectIdstring· pathRequired
The unique identifier for the monitored project.

Request Body

JSON
{
  "ingressToken": "DM_SECURE_TOKEN_XYZ"
}
ingressTokenstring
Security token for ingress authentication (can also be sent via X-Directory-Monitor-Token header).

Responses

Monitor successfully initialized.

{
  "status": "success",
  "projectId": "proj_123"
}

Request examples

curl --request POST 'https://api.hub.donutwork.com/2026-02-01/directory-monitor/PROJECTID.json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "ingressToken": "DM_SECURE_TOKEN_XYZ"
}'
const response = await fetch('https://api.hub.donutwork.com/2026-02-01/directory-monitor/PROJECTID.json', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.DONUTWORK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "ingressToken": "DM_SECURE_TOKEN_XYZ"
  }),
});
const requestId = response.headers.get('x-request-id');
if (!response.ok) {
  const error = await response.text();
  throw new Error(`${response.status} ${error} [${requestId}]`);
}
const contentType = response.headers.get('content-type') ?? '';
const data = response.status === 204 ? null
  : contentType.includes('application/json') ? await response.json()
  : await response.text();
$request = curl_init('https://api.hub.donutwork.com/2026-02-01/directory-monitor/PROJECTID.json');
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DONUTWORK_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "ingressToken": "DM_SECURE_TOKEN_XYZ"
}',
]);
$response = curl_exec($request);
if ($response === false) {
    $error = curl_error($request);
    curl_close($request);
    throw new RuntimeException($error);
}
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$contentType = (string) curl_getinfo($request, CURLINFO_CONTENT_TYPE);
curl_close($request);
if ($status >= 400) { throw new RuntimeException($response); }
$data = $status === 204 ? null
    : (str_contains($contentType, 'application/json')
        ? json_decode($response, true, flags: JSON_THROW_ON_ERROR) : $response);

Replace uppercase placeholders and sample values with your own data and company resource IDs. Keep the API key on a trusted server. Reuse an idempotency key only for the same logical request and payload.

Synchronize Event (Ingress)

Report a filesystem event (creation, modification, deletion) to the centralized monitor. This endpoint processes file metadata and executes any associated workflow triggers.

PUT
/2026-02-01/directory-monitor/{projectId}.json
Required permissiondirectory_monitor:write

Path, query, and header parameters

projectIdstring· pathRequired
The project identifier.

Request Body

JSON
{
  "projectId": "proj_123",
  "filename": "src/controllers/UserController.php",
  "event": "modified",
  "filesize": 4096,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "uid": 1000,
  "pid": 4512
}
projectIdstringRequired
Must match the projectId in the path.
filenamestringRequired
Relative path of the affected file.
eventstringRequired
Type of event (e.g., created, modified, deleted, renamed).
filesizeintegerRequired
Size of the file in bytes.
filetypestring
MIME type or file classification.
sha256string
SHA-256 hash of the file content for integrity verification.
uidinteger
User ID of the process owner.
pidinteger
Process ID that triggered the event.
timestampUtcstring
ISO 8601 timestamp of the local event.
ingressTokenstring
Authentication token.

Responses

Event successfully ingested and indexed.

{
  "status": "success",
  "eventId": "evt_7721...",
  "projectId": "proj_123",
  "inserted": true,
  "workflowTriggered": true
}

Request examples

curl --request PUT 'https://api.hub.donutwork.com/2026-02-01/directory-monitor/PROJECTID.json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "projectId": "proj_123",
  "filename": "src/controllers/UserController.php",
  "event": "modified",
  "filesize": 4096,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "uid": 1000,
  "pid": 4512
}'
const response = await fetch('https://api.hub.donutwork.com/2026-02-01/directory-monitor/PROJECTID.json', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer ' + process.env.DONUTWORK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "projectId": "proj_123",
    "filename": "src/controllers/UserController.php",
    "event": "modified",
    "filesize": 4096,
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "uid": 1000,
    "pid": 4512
  }),
});
const requestId = response.headers.get('x-request-id');
if (!response.ok) {
  const error = await response.text();
  throw new Error(`${response.status} ${error} [${requestId}]`);
}
const contentType = response.headers.get('content-type') ?? '';
const data = response.status === 204 ? null
  : contentType.includes('application/json') ? await response.json()
  : await response.text();
$request = curl_init('https://api.hub.donutwork.com/2026-02-01/directory-monitor/PROJECTID.json');
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DONUTWORK_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "projectId": "proj_123",
  "filename": "src/controllers/UserController.php",
  "event": "modified",
  "filesize": 4096,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "uid": 1000,
  "pid": 4512
}',
]);
$response = curl_exec($request);
if ($response === false) {
    $error = curl_error($request);
    curl_close($request);
    throw new RuntimeException($error);
}
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$contentType = (string) curl_getinfo($request, CURLINFO_CONTENT_TYPE);
curl_close($request);
if ($status >= 400) { throw new RuntimeException($response); }
$data = $status === 204 ? null
    : (str_contains($contentType, 'application/json')
        ? json_decode($response, true, flags: JSON_THROW_ON_ERROR) : $response);

Replace uppercase placeholders and sample values with your own data and company resource IDs. Keep the API key on a trusted server. Reuse an idempotency key only for the same logical request and payload.

Audit Monitor Events

Retrieve a paginated history of synchronized filesystem events for a specific project. This is used for auditing changes and verifying synchronization state.

GET
/2026-02-01/systems/directory-monitor/{projectId}/events.json
Required permissiondirectory_monitor:read

Path, query, and header parameters

projectIdstring· pathRequired
The project identifier.
sizeinteger· query
Number of events to return (max 200).
pageinteger· query
Pagination page number.
eventstring· query
Filter by event type (e.g., modified).
pathLikestring· query
Filter by partial file path.

Responses

Collection of project events retrieved.

{
  "status": "fetch",
  "projectId": "proj_123",
  "page": 1,
  "size": 50,
  "count": 120,
  "items": []
}

Request examples

curl --request GET 'https://api.hub.donutwork.com/2026-02-01/systems/directory-monitor/PROJECTID/events.json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
const response = await fetch('https://api.hub.donutwork.com/2026-02-01/systems/directory-monitor/PROJECTID/events.json', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer ' + process.env.DONUTWORK_API_KEY,
  },
});
const requestId = response.headers.get('x-request-id');
if (!response.ok) {
  const error = await response.text();
  throw new Error(`${response.status} ${error} [${requestId}]`);
}
const contentType = response.headers.get('content-type') ?? '';
const data = response.status === 204 ? null
  : contentType.includes('application/json') ? await response.json()
  : await response.text();
$request = curl_init('https://api.hub.donutwork.com/2026-02-01/systems/directory-monitor/PROJECTID/events.json');
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DONUTWORK_API_KEY'),
    ],
]);
$response = curl_exec($request);
if ($response === false) {
    $error = curl_error($request);
    curl_close($request);
    throw new RuntimeException($error);
}
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$contentType = (string) curl_getinfo($request, CURLINFO_CONTENT_TYPE);
curl_close($request);
if ($status >= 400) { throw new RuntimeException($response); }
$data = $status === 204 ? null
    : (str_contains($contentType, 'application/json')
        ? json_decode($response, true, flags: JSON_THROW_ON_ERROR) : $response);

Replace uppercase placeholders and sample values with your own data and company resource IDs. Keep the API key on a trusted server. Reuse an idempotency key only for the same logical request and payload.

TLS monitor

Previous Page

Webhooks

Next Page

On this page

Directory MonitorInitialize Monitor (Startup)Synchronize Event (Ingress)Audit Monitor Events