FilePulse local HTTP API

Developer API

Use FilePulse from AI agents, scripts, launchers, and internal tools through the same local HTTP API used by the web app.

Example base URLhttp://127.0.0.1:80

The default example uses port 80 from config_default.json. Real deployments should read the active port from the user's config.json.

Start here

Authentication Flow

Probe the service, sign in once, then pass the returned token as the raw Authorization header. Do not prefix it with Bearer.

GET/api/ver

Probe version and edition

Returns ver and plan. Online builds can also include uid and license_remaining_hours. This endpoint does not require a token.

Example request: /api/ver

curl http://127.0.0.1:80/api/ver

POST/api/login

Create an access token

Send username and password as JSON. The response contains server_name and access_token.

Example request: /api/login

curl -X POST http://127.0.0.1:80/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"root","password":"root"}'

Authorization: <access_token>

Call protected APIs

Use the returned token directly in the Authorization header or Authorization query parameter.

Example request: Authorization: <access_token>

curl http://127.0.0.1:80/api/search_scope_targets \
  -H "Authorization: $FILEPULSE_TOKEN"

Core surface

Useful Public Endpoints

These are the endpoints most useful for AI-assisted workflows: discover, search, preview, download, and open only after confirmation.

GET/api/search_scope_targets

Token

Searchable drives and scopes

Returns the indexed search targets. Use the returned drive indices when you want to limit search requests with drive_scope.

Important fields

Response drives can be passed as drive_scope.drive_indices.
Use drive_scope.local_only when an AI workflow should avoid remote mounted targets.

Example request: /api/search_scope_targets

curl http://127.0.0.1:80/api/search_scope_targets \
  -H "Authorization: $FILEPULSE_TOKEN"

POST/api/search

Token

File name and path search

Search indexed file and folder metadata with wildcard or regex matching, filters, sort order, and paging.

Important fields

mode: regex or wildcard
search_by: name or full_path
sort_by: name, full_path, size, modified, or ext
kind: 0 for files and folders, 1 for folders, 2 for files
pin_priority/use_groups control result grouping and pinned priority behavior
inline_icon.size asks the API to include inline icon data
start/end are inclusive result indexes

File search example

curl -X POST 'http://127.0.0.1:80/api/search' \
  -H 'Content-Type: application/json' \
  -H "Authorization: $FILEPULSE_TOKEN" \
  --data-raw '{
    "search_content": "a",
    "mode": "wildcard",
    "case_sensitive": false,
    "search_by": "name",
    "sort_by": "modified",
    "sort_asc": false,
    "content_plugin": [""],
    "kind": 0,
    "pin_priority": false,
    "use_groups": false,
    "start": 0,
    "end": 13,
    "inline_icon": {
      "size": 32
    }
  }'

POST/api/content_search

Token

Full-text content search

Search indexed document text, OCR text, and supported content handlers. Enable snippets when an AI needs context around each hit.

Important fields

linear false supports regular, regex, prefix, and fuzzy modes
linear true supports wildcard and regex traversal modes
sort_by: none, file, or score
file_search_condition can reuse /api/search filters before content search
snippet controls whether match context is returned
pin_priority/use_groups control result grouping and pinned priority behavior
inline_icon.size asks the API to include inline icon data

Example request: /api/content_search

curl -X POST 'http://127.0.0.1:80/api/content_search' \
  -H 'Content-Type: application/json' \
  -H "Authorization: $FILEPULSE_TOKEN" \
  --data-raw '{
    "linear": false,
    "search_content": "a",
    "mode": "regular",
    "fuzzy_distance": 2,
    "score_top_k": 100,
    "sort_by": "score",
    "sort_asc": false,
    "snippet": false,
    "snippet_radius": 100,
    "pin_priority": false,
    "use_groups": false,
    "start": 0,
    "end": 13,
    "inline_icon": {
      "size": 32
    }
  }'

GET/api/visual_status

Token

Visual search readiness

Reports whether visual search is enabled, indexing progress, ready file counts, descriptor rows, and ffmpeg availability.

Important fields

Check enabled and ready_files before sending image or video queries.
Use indexing/current_file_count/total_file_count to decide whether to wait.

Example request: /api/visual_status

curl http://127.0.0.1:80/api/visual_status \
  -H "Authorization: $FILEPULSE_TOKEN"

POST/api/visual_search

Token

Image and video similarity search

Submit multipart form data with a query image, screenshot, video, or an absolute query_path on the FilePulse host.

Important fields

file or query_path is required
drive_indices accepts a JSON array string
top_k limits matches
fast_mode trades detail for speed
search_detail and min_match_count tune video matching

Example request: /api/visual_search

curl -X POST 'http://127.0.0.1:80/api/visual_search' \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -F 'file=@query.jpg' \
  -F 'top_k=20' \
  -F 'drive_indices=[0]' \
  -F 'fast_mode=true'

GET/api/download/{encodedPath}

Token

Download or preview a file

Streams a local or proxied file path. Encode the full path in the URL and include Authorization. Range requests are supported by the file server.

Important fields

Use x-proxy only for registered remote server names.
Only file paths are accepted; folders return an error.

Example request: /api/download/{encodedPath}

curl 'http://127.0.0.1:80/api/download/D%3A%5Cdocs%5Creport.pdf' \
  -H "Authorization: $FILEPULSE_TOKEN" \
  --output report.pdf

POST/api/folder_preview

Token

Preview folder children

Returns a small sorted listing for a folder without downloading every child item.

Important fields

path is required
limit defaults to 80 and is capped at 200
Response includes total_children and truncated

Example request: /api/folder_preview

curl -X POST http://127.0.0.1:80/api/folder_preview \
  -H "Content-Type: application/json" \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -d '{"path":"D:\\docs","limit":50}'

POST/api/content_match_preview

Token

Preview a content match

Fetches HTML/text context for one content search result, useful when an AI should inspect a hit before asking to open the file.

Important fields

path, modified, search_content, and mode are required
linear and fuzzy_distance should match the original content search request

Example request: /api/content_match_preview

curl -X POST http://127.0.0.1:80/api/content_match_preview \
  -H "Content-Type: application/json" \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -d '{
    "path": "D:\\docs\\report.pdf",
    "modified": 1717113600,
    "search_content": "invoice",
    "mode": "regular",
    "linear": false,
    "fuzzy_distance": 2
  }'

POST/api/openfile

Token

Open a file on the host

Launches the file or executable on the FilePulse machine. This has side effects, so AI tools should ask the user for explicit confirmation first.

Important fields

path is required
work_folder can be empty to infer parent folder
admin controls elevated launch where supported

Example request: /api/openfile

curl -X POST http://127.0.0.1:80/api/openfile \
  -H "Content-Type: application/json" \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -d '{"path":"D:\\docs\\report.pdf","work_folder":"","admin":false}'

POST/api/quick_launcher

Token

Quick launcher search

Searches launchable apps, folders, and shortcuts with the same request shape as /api/search.

Important fields

Request body follows SearchReqJson
Useful for AI workflows that need to locate an app or frequent folder before launching.

Example request: /api/quick_launcher

curl -X POST http://127.0.0.1:80/api/quick_launcher \
  -H "Content-Type: application/json" \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -d '{
    "search_content": "chrome",
    "mode": "wildcard",
    "case_sensitive": false,
    "search_by": "full_path",
    "sort_by": "modified",
    "sort_asc": false,
    "content_plugin": [""],
    "kind": 0,
    "start": 0,
    "end": 9
  }'

Agent guidance

Recommended AI Workflow

Keep the model on a narrow path: authenticate, search, inspect, then ask before doing anything that opens or changes files.

ver

search / content_search / visual_search

preview / download

user-confirmed openfile

Keep credentials out of prompts

Ask the user or host app to provide a short-lived token. Do not store the password in model memory or long-running logs.

Treat openfile as a confirmed action

Opening a file can launch programs or reveal local data. The AI should present the exact path and wait for user approval.

Use small pages first

Start with end 9 or end 19, inspect names and snippets, then request more pages only when needed.

Not covered here

Advanced and Internal APIs

The following surfaces are intentionally omitted from this public starter page because they are internal, destructive, administrative, or better documented separately.

sync/**_internalconfiguration writesshare settingsLLM configurationduplicate cleanupupload

Back to home