http://localhost:6699/api/v1
Canonical files
These files are served directly from the docs site and are the best entry points for tools that need to inspect the API.OpenAPI YAML
Raw OpenAPI 3.0 contract for endpoint discovery, schemas, and generated clients.
OpenAPI JSON
Raw JSON mirror of the OpenAPI contract.
Markdown Reference
Markdown export with examples, workflow notes, and endpoint behavior.
Authentication
Every endpoint exceptGET /health requires a Jumper Pro license key on every request. The UI and API use the same Pro entitlements; no separate API entitlement is needed. Activating Jumper in the UI does not authenticate your script.
Use the X-License-Key header with the raw key. A non-empty JSON license_key takes precedence over the header. The API accepts local requests on the machine running Jumper.
A
403 with error: "Jumper Pro license required" can mean an invalid key. Read the response’s message for the validation reason. A valid non-Pro key can return message: "OK" with 403. Enterprise policy denials return policy_error.
For access diagnostics, preserve the HTTP status and complete response body from GET /models/loaded. A successful /health request or Socket.IO connection only establishes connectivity.
Typical workflow
1
Check health
Verify the backend is running with
GET /health.2
Analyze media
Run visual analysis, transcription, optional face clustering, and optional Summary Analysis with
POST /analyze. REST analysis runs directly and does not require MCP, an agent, or approval prompts.3
Track progress
Use the returned
task_id with Socket.IO progress events. In Socket.IO terms, emit join with the task_id, then listen for progress.4
Read summaries
Discover completed analyses with
POST /summaries/list or POST /summaries/collections, then read an overview and drill into selected nodes. This step is optional when Summary Analysis was not requested.5
Load analysis data
Load all analysis data with
POST /analysis-data/load, ensure visual data for selected media is loaded with POST /analysis-data/load-for-media, or load transcript-only data with POST /analysis-data/load-transcriptions. Loading selected media can also load the unified visual cache; it does not restrict later searches to those files.6
Search and retrieve
Search visually, search transcripts, fetch transcriptions, get thumbnails, inspect face clusters, or export clips and transcripts.
Endpoint groups
Important behavior notes
Analysis tasks
Analysis tasks
Only one analysis task can run at a time per backend instance. A new
POST /analyze request first asks the current task to stop. If the previous task is still unwinding, Jumper returns 409. The returned REST task_id identifies a Socket.IO room; there is currently no durable REST status or resume endpoint.Summary Analysis
Summary Analysis
Summary Analysis requires a supported Apple silicon or Windows device, a downloaded Summary model, and complete visual analysis for each file. Include the same path in
visual_media_paths to generate the visual dependency in one request. Use the /summaries/* read endpoints instead of depending on private cache files.Visual search results
Visual search results
POST /search/text, POST /search/image, and POST /search/frame return matches ordered best-first, but they do not return similarity scores. The optional exclude field is a soft ranking signal, not a hard filter.People filters
People filters
Use
people_filter on POST /search/text to restrict visual search results to named people or cluster IDs. When multiple people are supplied, people_filter_mode defaults to "and", which requires every selected person in the same frame; set it to "or" to match frames containing any selected person.Search match fields
Search match fields
Visual search matches use
frame_idx as a string on the 1-FPS embedding grid, include a base64 JPEG image, and provide scene_start_timestamp, scene_end_timestamp, hash_str, and video_path.Face reference images
Face reference images
POST /analyze accepts named sample_faces with local image paths or base64 images. Top-level samples supply defaults for all face jobs; a job’s samples override them. Confident matches are named after clustering and before Summary Analysis. See the Markdown reference for limits and examples.Watch folder options
Watch folder options
Watch folders support
excluded_extensions, excluded_filename_globs, and metadata_filter_request. Glob patterns match the filename only, not the full path. Speech options include channel selection, speaker detection, and Qwen model preference. Saving an enabled folder does not start the service; use POST /watch-folders/service/start.Transcript exports
Transcript exports
Use
POST /export/transcript to export transcript segments to txt, csv, docx, or pdf. Export rows accept an optional speaker label in their fourth field. Legacy /transcriptions rows use that field for the media path, so drop or replace it before export.