HTTP API

HTTP API

The web interface is a thin client over an HTTP API bound to 127.0.0.1:3030 by default. Long-running operations return a job id and are polled with /api/job.

A root-privileged engine requires a session token on every request — send it as the X-Ghost-Token header, or as ?tok= on /api/content for media tags and downloads.

System

Method	Path	Description
GET	/api/health	engine state: version, is_root, output_root, writes_allowed, carver/filesystem counts, can_elevate, elevate_method
GET	/api/disks	block devices (name, type, size, accessible, filesystem, mountpoint)
GET	/api/filesystems	list of supported filesystems
GET	/api/carvers	carver signatures by category
GET	/api/browse?path=~	file browser for picking images and output directories
GET	/api/privileges	elevation capability: pkexec, sudo, sudo_nopasswd, preferred, inaccessible_disks
POST	/api/elevate	start the unlock flow (see Elevation and security)
GET	/api/elevate/status	poll the unlock flow
POST	/api/handover	privilege hand-off between the unprivileged and privileged instances
POST	/api/shutdown	stop the engine

Sources

Method	Path	Description
POST	/api/detect	identify the filesystem on a device or image
POST	/api/partitions	list partitions; find_deleted finds deleted ones

Jobs

Method	Path	Description
POST	/api/scan	filesystem scan → { job }
POST	/api/carve	signature carving → { job }
POST	/api/deep	scan + carve merged → { job }
POST	/api/extract	write recovered files to the output root → { job }
POST	/api/image	clone a device to an image, tolerating bad sectors → { job }
POST	/api/raid/detect	detect RAID geometry from member images → { job }
POST	/api/raid/assemble	assemble an array (optionally with a missing member) → { job }
POST	/api/repair	dry-run repair of boot regions / GPT headers (apply only with --allow-writes)
GET	/api/job?id=JOB	job state: phase, progress, bytes scanned, candidates, files
GET	/api/jobs	list all jobs
POST	/api/job/cancel	cancel the running job

Results

Method	Path	Description
GET	/api/results?job=&offset=&limit=&q=&ext=&only=&sort=	paged, searchable results
GET	/api/fileinfo?job=&index=	metadata for one result (size, dates, allocation, extents…)
GET	/api/content?job=&index=[&max=]	file bytes — previews and downloads
GET	/api/hex?job=&index=	hex dump view
GET	/api/file?path=	read a file under the output root only
POST	/api/save	save a recovered file to the output root

Behaviour notes

• Previews stream window-by-window and answer HTTP Range requests natively, so players can seek through multi-gigabyte files. max= bounds a preview's byte budget; the response carries X-Content-Truncated: 1 when the cap applies. Downloads always receive the complete file.
• /api/file only serves paths under the output root — the engine will not read arbitrary files off the host.
• output_dir for /api/extract must also live under the output root (/api/health reports it).
• Every API call is rejected with 403 when a session token is required but missing; non-OPTIONS requests from non-loopback hosts or origins are rejected too (see Elevation and security).