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. Find the same recording in audio and video by sound, and locate its positions.

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/audio_status

Token

Audio Search readiness

Check audio search readiness, searchable file counts, indexing progress, and FFmpeg availability.

Important fields

Check ffmpeg_available, rules, and ready_files before querying; enabled does not mean media is ready to search.
Use indexing, current_file_count, and total_file_count to show indexing progress.

Example request: /api/audio_status

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

POST/api/audio_search

Token

Audio and video recording search

Submit audio or video with multipart form data to find the same recording and its positions in indexed media. Use the existing Authorization Token authentication.

Important fields

Submit file, or an absolute query_path on the FilePulse service host. The two examples show these input methods separately.
drive_indices is a JSON array string of search drive IDs. Omit it to search all connected scopes; an empty array is invalid.
Supply query_start_ms and query_end_ms together, in milliseconds. The end must be later than the start, and the query segment must be at least 5 seconds.
top_k limits returned files to 1–100 and defaults to 50 when omitted. Configure audio index rules and index target media in the app first.

Upload a file and search a selected range

curl -X POST http://127.0.0.1:80/api/audio_search \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -F "file=@query.mp3" \
  -F "query_start_ms=10000" \
  -F "query_end_ms=25000" \
  -F "top_k=20"

Use a file on the service host

curl -X POST http://127.0.0.1:80/api/audio_search \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -F "query_path=D:/media/query.mp3" \
  -F "drive_indices=[0]" \
  -F "top_k=20"

total is the total number of matching files. data may contain multiple position records for one file; top_k limits files rather than positions. Time fields use milliseconds, and track IDs distinguish media tracks. Check warnings for search scopes that did not complete. HTTP error responses contain error.

Common response fields (excerpt)

{
  "total": 1,
  "data": [
    {
      "server_name": "local",
      "name": "recording.mp4",
      "full_path": "D:/media/recording.mp4",
      "media_kind": "video",
      "query_stream_index": 0,
      "target_stream_index": 1,
      "query_start_ms": 10000,
      "query_end_ms": 25000,
      "target_start_ms": 65000,
      "target_end_ms": 80000
    }
  ],
  "warnings": []
}

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 / audio_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