Skip to main content
POST
/
api
/
watch
/
directory
{
  "status": "<string>",
  "data": {
    "directory": "<string>",
    "files_found": 123,
    "indexing_started": true
  }
}
Add a directory to the watch list and start indexing all files within it.

​
Request

​
path
string
required
Absolute path to the directory to watch and indexExample: /Users/username/Downloads

​
Request Example

cURL
curl -X POST http://localhost:60534/api/watch/directory \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/Users/username/Downloads"
  }'
Python
import requests

response = requests.post(
    'http://localhost:60534/api/watch/directory',
    json={'path': '/Users/username/Downloads'}
)

print(response.json())
JavaScript
const response = await fetch('http://localhost:60534/api/watch/directory', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    path: '/Users/username/Downloads'
  })
});

const data = await response.json();
console.log(data);

​
Response

​
status
string
Status of the request: success or error
​
data
object

​
Response Example

200 Success
{
  "status": "success",
  "data": {
    "directory": "/Users/username/Downloads",
    "files_found": 127,
    "indexing_started": true
  }
}
400 Invalid Path
{
  "status": "error",
  "error": {
    "code": "INVALID_PATH",
    "message": "Directory does not exist or is not accessible"
  }
}
409 Already Watching
{
  "status": "error",
  "error": {
    "code": "ALREADY_WATCHING",
    "message": "This directory or a parent directory is already being watched"
  }
}

​
Behavior

When you watch a directory:
  1. Directory Validation: Checks if the path exists and is accessible
  2. Duplicate Check: Verifies this directory (or parent) isn’t already watched
  3. Database Entry: Adds directory to watched_directories table
  4. File Discovery: Recursively scans for all files
  5. Pipeline Start: Begins processing files through the 4-stage pipeline
  6. File Watcher: Starts monitoring filesystem for changes
The indexing process runs asynchronously. Use the /api/updates endpoint to monitor progress in real-time.
Watching very large directories (thousands of files) may take significant time to complete initial indexing. The backend processes files sequentially to avoid overwhelming system resources.