Jumper Public API v1

Base URL: http://localhost:6699/api/v1 Jumper analyzes your media files locally on your machine. This API lets external tools (MAM systems, automation scripts, custom integrations) tap into those capabilities: semantic search across video, speech transcription, face detection and clustering, and more.

Authentication

Every endpoint except /health requires a Jumper Pro license key. Pass it one of two ways:

Method	Example
Header (recommended)	`X-License-Key: your-key-here`
JSON body	`{"license_key": "your-key-here", ...}`

A non-empty JSON license_key takes precedence over the header. Send the raw key without quotes around the value or a Bearer prefix. The UI and API use the same Pro entitlements; no separate API entitlement is needed. Successful key validation is cached for 30 minutes. Requests with the same key within that window can skip the network check; the key is validated again after the cache expires. When an on-prem license server is configured in Jumper, this validation uses the signed machine-file forwarding flow instead of contacting Keygen directly. /auth_by_settings is an internal bootstrap endpoint and does not authenticate later /api/v1 calls by itself. Public API clients should still send X-License-Key or license_key on each /api/v1 request. Error responses:

Status	Meaning
`401`	No license key provided
`403`	Supplied key could not be validated, lacks Pro entitlements, or an Enterprise policy denied the action

// 401
{"error": "Authentication required", "message": "Provide license_key in request body or X-License-Key header"}

// 403
{"error": "Jumper Pro license required", "message": "License invalid and activation not required: license does not exist"}

Jumper Pro license required covers both invalid keys and valid non-Pro keys. Inspect the actual response message to distinguish them. A valid non-Pro key can return message: "OK" with HTTP 403. Enterprise policy denials use policy_error instead of error and message. Activating Jumper in the UI does not authenticate your script. A failing API request can coexist with a valid Pro session when the script sends a different key. To check access before submitting media, use the same key that works in the UI:

curl -i -H "X-License-Key: YOUR_KEY" http://127.0.0.1:6699/api/v1/models/loaded

Preserve the HTTP status and complete response body when diagnosing a failure. /health and a successful Socket.IO connection only establish connectivity; they do not prove API authorization. The public API accepts local requests on the machine running Jumper.

Typical Workflow

Most integrations follow this pattern:

Check health — verify the backend is running
Analyze media — run visual and/or speech analysis on your files
Orient with summaries — compare one-line overviews and drill into relevant time ranges when summaries exist
Load analysis data — load analysis results into memory for searching
Search — find matching moments, optionally constrained to summary-derived ranges
Verify evidence — retrieve transcriptions and thumbnails before making source claims or edit decisions

Endpoints

Health

`GET /health`

No authentication required. Use this to check if the backend is running. Response:

{"status": "ok"}

Models

`GET /models/loaded`

Returns which visual and speech analysis models are currently loaded in memory. Example request:

curl -H "X-License-Key: YOUR_KEY" http://localhost:6699/api/v1/models/loaded

Response:

{
  "visual": {
    "model_key": "v2-medium-256",
    "is_loading": false,
    "requested_model_key": "v2-medium-256",
    "load_status": "ready",
    "load_error": null,
    "fallback_from": null
  },
  "speech": {
    "model_key": "mlx-large-v3-turbo",
    "is_loading": false
  }
}

model_key is the model actually loaded and may be null. requested_model_key is the model Jumper attempted to load. load_status is loading, ready, failed, or unavailable; after a successful fallback, fallback_from contains the requested model key and model_key contains the default model that was loaded instead.

`GET /models/available`

Lists all visual models supported on this hardware, which are downloaded, and which is active. Example request:

curl -H "X-License-Key: YOUR_KEY" http://localhost:6699/api/v1/models/available

Response:

{
  "supported_models": ["v2-medium-256", "v2-large-384", "v1-multilingual-384"],
  "downloaded_models": ["v2-medium-256", "v2-large-384"],
  "loaded_model": "v2-medium-256",
  "requested_model": "v2-medium-256",
  "load_status": "ready",
  "load_error": null,
  "fallback_from": null,
  "model_info": [
    {"v2-medium-256": {"speed": 5, "accuracy": 3, "frame_resolution": 256, "size_gb": 0.6, "compatible_os": ["mac-arm", "mac-x86", "windows"], "is_multilingual": false}}
  ],
  "current_system": "mac-arm"
}

model_info is an array of single-key objects, where each key is a model_key from supported_models. current_system is one of mac-arm, mac-x86, windows, or linux. loaded_model may be null while loading or after a terminal load failure. The requested, status, error, and fallback fields have the same meaning as on /models/loaded.

`POST /models/load`

Switches to a different visual model. The model must already be downloaded. This clears loaded visual analysis data from memory — you’ll need to reload it afterwards. Example request:

curl -X POST http://localhost:6699/api/v1/models/load \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_key": "v2-large-384"}'

Response:

{
  "message": "Model changed from V2 Medium to V2 Large high-res in 3.24s",
  "loaded_model": "v2-large-384"
}

Status	Meaning
`200`	Model switched, already active, or switch deferred with a `warning` while model loading, analysis, or analysis preload is running
`400`	Model key invalid or not downloaded
`500`	Loading failed

Media Metadata

`POST /media/metadata`

Returns file properties (duration, FPS, timecode) and analysis status for each file. This is the way to check which files have been analyzed and to get their hash_str identifiers. Invalid or unreadable media files are omitted; if none can be parsed, the response is 400. An unavailable Analysis folder returns 503. Example request:

curl -X POST http://localhost:6699/api/v1/media/metadata \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_paths": [
      "/Videos/interview.mp4",
      "/Videos/photo.jpg",
      "/Audio/voiceover.mp3"
    ]
  }'

Response:

{
  "media_properties": {
    "/Videos/interview.mp4": {
      "video_cached": true,
      "audio_cached": true,
      "runtime": "00:02:30",
      "fps": 30,
      "media_path": "/Videos/interview.mp4",
      "timecode": "00:00:00:00",
      "hash_str": "1e09e4953de0471b"
    },
    "/Videos/photo.jpg": {
      "video_cached": true,
      "audio_cached": false,
      "runtime": "00:00:01",
      "fps": 0,
      "media_path": "/Videos/photo.jpg",
      "timecode": "00:00:00:00",
      "hash_str": "fba6b4a2d2cf672c"
    },
    "/Audio/voiceover.mp3": {
      "video_cached": false,
      "audio_cached": true,
      "runtime": "00:00:03",
      "fps": 0,
      "media_path": "/Audio/voiceover.mp3",
      "timecode": "00:00:00:00",
      "hash_str": "485535a3914b2d02"
    }
  }
}

Fields explained:

video_cached — true if visual analysis data exists (for videos/images)
audio_cached — true if a transcription exists (for videos/audio)
hash_str — unique identifier for this file, used internally and in other endpoints

Analysis

`POST /analyze`

Starts analyzing media files. This is asynchronous — it returns immediately with a task_id, and the actual work runs in the background. You can combine visual analysis, transcription, face clustering, and named hierarchical summaries in one call. Summary generation requires a supported Apple silicon or Windows device and a locally downloaded Summary model. The REST endpoint is headless: it does not require MCP, an agent, or an approval step. Batching matters: one request with 50 files is much faster than 50 one-file requests on the same backend, because Jumper loads the ML models per analysis request. Only one analysis task can run at a time per backend instance. A new /analyze request first tries to stop any current task. If the previous task is still unwinding, the new request returns 409. Example request — visual + transcription + face clustering:

curl -X POST http://localhost:6699/api/v1/analyze \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "detect_speakers": true,
    "speaker_count": "auto",
    "preferred_qwen_model_key": "more accurate",
    "visual_media_paths": [
      "/Videos/interview.mp4",
      "/Videos/photo.jpg"
    ],
    "transcription_jobs": [
      {"path": "/Videos/interview.mp4", "language": "english", "channels": [1, 3]},
      {"path": "/Audio/voiceover.mp3", "language": "english"}
    ],
    "face_clustering_jobs": [
      {
        "cluster_job_name": "Interview Faces",
        "face_media_paths": [
          "/Videos/interview.mp4"
        ],
        "face_eps": 0.48,
        "face_min_samples": 5
      }
    ]
}'

detect_speakers is optional and defaults to true. Set it to false to skip final speaker diarization for the speech batch. speaker_count is optional and defaults to "auto"; accepted values are "auto", 1, 2, 3, 4, and "5+". For pyannote, 1-4 becomes num_speakers, while "5+" becomes min_speakers=5, max_speakers=12. preferred_qwen_model_key is optional and applies to Qwen-supported languages; use "faster" for the 0.6B model, "more accurate" for the 1.7B model, or "auto"/omit it for Jumper’s default. detect_speakers, speaker_count, and preferred_qwen_model_key can also be supplied on individual transcription_jobs to override the batch setting. Example request — with face clustering:

curl -X POST http://localhost:6699/api/v1/analyze \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "visual_media_paths": ["/Videos/interview.mp4"],
    "transcription_jobs": [],
    "face_clustering_jobs": [
      {
        "cluster_job_name": "Interview Faces",
        "face_media_paths": ["/Videos/interview.mp4"],
        "face_eps": 0.48,
        "face_min_samples": 5,
        "sample_faces": [
          {"name": "John Johnsson", "face_paths": ["/Photos/john.jpg"]}
        ]
      }
    ]
  }'

Response (202):

{
  "message": "Analysis started",
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}

face_clustering_jobs[].sample_faces optionally supplies named reference images for that collection. Each person needs a non-empty name and 1–3 images total across face_paths (local paths readable by Jumper) and face_images (base64 image bytes or data:image/...;base64,...). Each image must show one face. For clipboard images or browser uploads, send face_images; native local file selection can use face_paths. Remote image URLs are not accepted. Limits are 100 people per sample array, 200 characters per name, 10 MiB and 24 megapixels per image, and 50 MiB of inline image bytes across the request. Top-level sample_faces supplies defaults to every requested face collection. A job’s explicit sample_faces overrides those defaults, including [] to skip automatic naming for that job. Supplying samples without a valid face job is an input error. After clustering, confident matches receive their supplied names before Summary Analysis. Unmatched or ambiguous references do not assign names; inspect the sample_face_naming progress result for assignments and reasons. Tracking progress: Connect to the SocketIO server at http://localhost:6699, emit join with the returned task_id, then listen for progress events:

{
  "progress": 45.5,
  "video_path": "/Videos/interview.mp4",
  "done": false,
  "type": "video"
}

The REST task_id identifies the Socket.IO room. There is currently no durable REST job-status or resume endpoint, so unattended clients should retain the socket events and confirm generated summaries with the read endpoints below. Analysis endpoints accept explicit file paths; enumerate folders in the client before submitting a batch. Summary events use type: "summary". During processing they may include summary_stage (loading_model, preparing_evidence, generating_observations, generating_summary, or generating_short_summary) and summary_node_id. Asynchronous failures include summary_error. Clients should accept progress as either a JSON number or a decimal string because Summary events currently format it as a string.

Status	Meaning
`202`	Analysis started
`400`	Invalid input, no valid media files supplied, or Summary Analysis is unsupported on this platform
`409`	Another analysis task is still stopping, or the selected Summary model is not downloaded
`503`	Models still loading, try again shortly

Transcription job fields:

Field	Type	Default	Description
`path`	string	required	Video or audio file to transcribe
`language`	string	`english`	Spoken language hint
`channels`	integer array, `null`, or empty array	legacy downmix	Omit, set to `null`, or pass `[]` to use Jumper’s legacy downmix-to-mono extraction. Pass a non-empty array to explicitly transcribe 1-based audio channel/track numbers; `[1]` means only channel 1. Multiple selected channels are analyzed separately, then merged with conservative near-duplicate removal.
`detect_speakers`	boolean	batch setting	Override the top-level speaker diarization setting for this file.
`speaker_count`	integer or string	batch setting	Override the top-level speaker-count hint for this file.
`preferred_qwen_model_key`	string	batch setting	Qwen model preference for Qwen-supported languages. Use `"faster"`, `"more accurate"`, or `"auto"`.

summary_requests is an optional array of per-file configurations. Visual analysis is the only required dependency: each path must already have complete visual analysis or also appear in visual_media_paths in the same request. Missing or disabled transcript and face evidence is non-fatal. Omitting collection creates a standalone analysis and is the default. Collections only organize independent per-file analyses; they do not combine clips or produce collection-level summaries. Collection names reuse existing records case-insensitively while preserving their canonical stored name and description. Summary request fields:

Field	Type	Default	Description
`path`	string	required	Visual media file to summarize.
`analysis_id`	string	generated	Stable ID to use when replacing or addressing a named analysis.
`analysis_name`	string	generated	Human-readable name for this analysis.
`collection`	object or `null`	`null`	Optional grouping with required `name` and optional `id` and `description`. Omit or use `null` for a standalone analysis.
`footage_context`	string or `null`	`null`	Factual operator context about the footage. It guides the prompt but is not source evidence.
`summary_objective`	object	general understanding	Editorial objective with `preset`, optional `description`, and optional `priority_hints`.
`use_transcript`	boolean	`true`	Use an existing transcript when available. Missing transcript evidence is non-fatal.
`output_language`	string	`auto`	`auto` or a lowercase ISO language code such as `en` or `sv`.
`face_collection`	string or `null`	`null`	Existing face-clustering job name used to resolve named people. Missing face evidence is non-fatal.
`summary_model_key`	string	recommended model	Optional platform-compatible Summary model key. The selected model must already be downloaded.

Supported summary_objective.preset values are general_understanding, trailer_teaser, action_trailer, visual_showcase, highlight_reel, event_recap, documentary_research, unscripted_story, interview_selects, archive_discovery, season_theme_analysis, b_roll_selects, social_cutdown, character_storyline_tracking, continuity_review, and custom. Supported priority_hints are beauty_scale, action_danger_violence, conflict, reactions, humor, reveals_reversals, strong_dialogue, people_relationships, claims_evidence, themes_contradictions, rare_material, clean_coverage, processes_demos, crowd_energy, locations_atmosphere, and resolutions_open_questions. Windows Summary model keys are qwen3-vl-2b-instruct, qwen3-vl-4b-instruct, and qwen3-vl-8b-instruct. Apple silicon keys are qwen3-vl-4b-instruct-8bit, qwen3-vl-8b-instruct-8bit, and qwen3-vl-32b-instruct-8bit. Omit summary_model_key to use Jumper’s recommended model for the machine. Download the model in the Jumper UI before starting the REST job. Example request — visual + Summary Analysis:

curl -X POST http://localhost:6699/api/v1/analyze \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "visual_media_paths": ["/Videos/episode-03.mov"],
    "summary_requests": [
      {
        "path": "/Videos/episode-03.mov",
        "analysis_id": "story-pass",
        "analysis_name": "Episode 3 story pass",
        "collection": {
          "name": "Season 2",
          "description": "Broadcast episodes and selected archive material"
        },
        "footage_context": "An unscripted television episode about commercial fishing",
        "summary_objective": {
          "preset": "unscripted_story",
          "description": "Preserve decisions, reversals, disagreements, and supported reactions",
          "priority_hints": ["reveals_reversals", "conflict"]
        },
        "use_transcript": true,
        "output_language": "auto",
        "face_collection": "Season 2 Cast"
      }
    ]
  }'

`POST /analyze/cancel`

Requests cancellation of any running analysis task. Returns 200 when the task has stopped (or no task is running), or 202 with still_stopping: true while the task is still unwinding.

curl -X POST http://localhost:6699/api/v1/analyze/cancel \
  -H "X-License-Key: YOUR_KEY"

Response:

{"message": "Cancellation requested"}

Hierarchical Summaries

Summaries are a bounded navigation layer over media. Start with a one-line overview, drill only promising branches, and use each node’s search_scope to constrain later searches. Summary prose is not source proof; verify exact facts, identities, quotations, and edit points with frame, transcript, or people evidence. Use these REST endpoints instead of reading summaries/<hash>/summary_v3.json directly. Cache artifacts and their directory layout are private implementation details and may change between Jumper releases. Summary reads access persisted artifacts directly and do not require /analysis-data/load.

`POST /summaries/collections`

Lists named collections and counts without enumerating or returning members by default. This is the inexpensive global discovery route. To expand one collection, pass its collection_id with include_members: true. The response contains every member of only that collection without a 500-member cap. Each compact registry-backed member contains only summary_ref, hash_str, media_path, media_basename, analysis_id, and analysis_name; fetch the selected analysis through /summaries/overview.

`POST /summaries/list`

Lists named analyses and one-line summaries for selected media_paths or hash_strs. This is not global discovery: omitting both selectors returns an empty summaries array.

`POST /summaries/overview`

Pass cache_dir and either summary_ref or one of path/hash_str with an optional analysis_id. Prefer the summary_ref returned during discovery because it uniquely identifies the media and named analysis. The response contains the same summary_ref, analysis metadata, short_summary, the full selected root text, and truncated previews of its immediate children.

`POST /summaries/node`

Pass the same selector plus node_id, keeping the summary_ref from the overview attached to every request because node IDs are local to one analysis. The response contains the same summary_ref, that node, and its immediate children. Set include_evidence: true on a leaf to receive a top-level evidence object containing compact sampled-frame references, transcript excerpts, speaker names, named people, and attribution hints. Image bytes and embeddings are never returned. Nodes may include bounded verification_hints. Each hint identifies an evidence limitation, affected range, supporting evidence IDs, and a suggested follow-up such as checking people/transcript context or reading a bounded transcript range. These are actionable source checks, not claims that the summary is wrong. Overview and node responses also include quality for the selected analysis as a whole, even when reading a subtree. Unreadable sampled images appear in warnings; intervals with no readable images appear in uncovered_ranges (start_seconds, end_seconds) and an explicit coverage warning. Other readable images and intervals are still summarized. Use this field to disclose missing evidence instead of relying on the generated summary text to mention it. The lists failed_node_ids, uncovered_ranges, and warnings contain at most eight entries each; warning strings are limited to 500 characters. Their full counts are failed_node_count, uncovered_range_count, and warning_count. The corresponding flags are failed_nodes_truncated, uncovered_ranges_truncated, and warnings_truncated. Every node includes a half-open 1 FPS search range:

{
  "search_scope": {
    "1e09e4953de0471b": [0, 300]
  }
}

Pass this object unchanged as segments_to_frame_indices to a visual search to search only the first five minutes.

Analysis Data Management

Before you can search, the analysis data needs to be loaded into memory. There are two approaches:

`POST /analysis-data/load`

Loads analysis data from the folder into memory — visual embeddings for the active visual model, people metadata, and transcriptions. Requires a loaded visual model (503 if none is loaded). A visual-model or Analysis-folder change while loading returns 409. Use /analysis-data/load-transcriptions for transcript-only workflows.

curl -X POST http://localhost:6699/api/v1/analysis-data/load \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cache_dir": "/Users/me/JumperAnalysis"}'

Response:

{"message": "Analysis data loaded in 0.45s"}

`POST /analysis-data/load-for-media`

Loads missing visual analysis data for specific video/image files. If no visual analysis context is loaded, Jumper first loads the folder’s unified visual data, which may include other media. It then supplements that data with missing requested files and skips files already in memory. An existing context must match the requested Analysis folder and active visual model; a mismatch or a context change while loading returns 409. A missing visual model or unreadable Analysis folder returns 503. This endpoint does not load transcriptions. Use /analysis-data/load to load everything, or /analysis-data/load-transcriptions for transcript-only workflows.

curl -X POST http://localhost:6699/api/v1/analysis-data/load-for-media \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_paths": ["/Videos/interview.mp4"]
  }'

Response:

{"message": "Loaded analysis data for 1 files in 0.12s"}

`POST /analysis-data/load-transcriptions`

Loads transcription data into memory separately. This is useful if you only need transcript search and don’t want to load visual analysis data. Transcriptions are also loaded automatically by /analysis-data/load.

curl -X POST http://localhost:6699/api/v1/analysis-data/load-transcriptions \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cache_dir": "/Users/me/JumperAnalysis"}'

Response:

{"message": "Loaded 123 transcriptions in 0.09s"}

Metadata Filters

`POST /metadata/facets`

Returns curated metadata filter facets and coverage for a searchable scope. Call this when you need to render metadata filter options, then pass selected filters to search as metadata_filter_request. For search_all: true or scope.mode: "global", the response is scoped to the backend’s loaded searchable media for the requested media_type (visual, speech, or any), not every row in the local metadata database. Example request:

curl -X POST http://localhost:6699/api/v1/metadata/facets \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_type": "visual",
    "search_all": true,
    "filters": []
  }'

Path-scoped request with known hashes:

{
  "cache_dir": "/Users/me/JumperAnalysis",
  "scope": {
    "mode": "paths",
    "media_type": "visual",
    "media_paths": ["/Videos/interview.mp4"],
    "hash_strs": ["1e09e4953de0471b"],
    "expected_count": 1
  },
  "filters": []
}

media_paths and hash_strs are index-aligned. For path scopes, supply hashes returned by /media/metadata; this endpoint does not hash source files automatically. Paths without supplied hashes count as missing coverage and produce no facet options. If you omit scope, Jumper derives it from search_all, media_type, media_paths, hash_strs, and expected_count. Response:

{
  "success": true,
  "coverage": {
    "scope_count": 583,
    "indexed_count": 423,
    "missing_count": 160
  },
  "active_filter_count": 0,
  "warning": "Metadata available for 423 of 583 media included in search",
  "facets": [
    {
      "id": "video.codec",
      "label": "Codec",
      "group": "Video",
      "path": ["Video", "Codec"],
      "kind": "single",
      "options": [
        {"value": "red", "label": "RED", "count": 5},
        {"value": "h264", "label": "H.264", "count": 42}
      ]
    },
    {
      "id": "video.bitrate_range",
      "label": "Video bitrate",
      "group": "Video",
      "path": ["Video", "Video bitrate"],
      "kind": "single",
      "options": [
        {"value": "10-50mbps", "label": "10-50 Mbps", "count": 81}
      ]
    }
  ]
}

Facet IDs and option values are intentionally stable API values. Option labels are for display. The facet list is curated; low-value raw fields such as exact duration seconds, exact frame counts, codec levels, and noisy object-like timecode values are omitted. Using selected filters in search:

{
  "query": "dog on a beach",
  "cache_dir": "/Users/me/JumperAnalysis",
  "search_all": true,
  "metadata_filter_request": {
    "filters": [
      {"facet_id": "video.codec", "operator": "is_any_of", "values": ["red"]},
      {"facet_id": "video.bitrate_range", "operator": "is_any_of", "values": ["50-100mbps"]}
    ]
  }
}

Supported operators are is_any_of, is_not, include_any_of, include_all_of, exclude_any_of, exclude_all_of, before, after, greater_than, and less_than.

Search

All search endpoints require analysis data to be loaded into memory first (see above). Visual search returns HTTP 400 while Summary Analysis is running. The visual search endpoints (/search/text, /search/image, /search/frame) return the same match structure and order results best-first. Jumper does not return similarity scores in the response payload. The optional exclude field is a soft ranking signal, not a hard filter. metadata_filter_request applies hard metadata filters from /metadata/facets. segments_to_frame_indices applies one or more half-open per-media ranges on the 1 FPS analysis grid and intersects with people and metadata filters.

`POST /search/text`

Semantic visual search — describe what you’re looking for in plain language. Example request:

curl -X POST http://localhost:6699/api/v1/search/text \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "dog on a beach",
    "exclude": ["water", "swimming pool"],
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_paths": ["/Videos/interview.mp4"],
    "max_results": 10
  }'

Response:

{
  "matches": [
    {
      "frame_idx": "76",
      "timestamp": "00:01:16",
      "image": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
      "scene_start_timestamp": "00:01:10",
      "scene_end_timestamp": "00:01:19",
      "hash_str": "1e09e4953de0471b",
      "video_path": "/Videos/interview.mp4"
    },
    {
      "frame_idx": "107",
      "timestamp": "00:01:47",
      "image": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
      "scene_start_timestamp": "00:01:43",
      "scene_end_timestamp": "00:01:52",
      "hash_str": "1e09e4953de0471b",
      "video_path": "/Videos/interview.mp4"
    }
  ]
}

frame_idx is the frame number on the 1-FPS embedding grid, returned as a string. Results are returned in rank order. If some analysis or frames could not be read, the response includes a toast_warning alongside the available matches. Parameters:

Parameter	Type	Default	Description
`query`	string	required	What you’re looking for
`cache_dir`	string	required	Analysis data folder
`media_paths`	string[]	`[]`	Restrict to these files
`max_results`	int	50	Maximum matches to return
`search_all`	bool	false	Search all loaded media (ignores `media_paths`)
`text_weight`	number	1	Text similarity weight (advanced)
`exclude`	string[]	`[]`	Visual concepts to softly push down in the ranking
`people_filter`	object[]	`[]`	Only show results containing specific people
`people_filter_mode`	string	`and`	`"and"` requires all selected people in the same frame; `"or"` matches any selected person
`metadata_filter_request`	object	optional	Metadata filters from `/metadata/facets`. If `scope` is omitted, Jumper derives it from `search_all` and `media_paths`.
`segments_to_frame_indices`	object	optional	Selected media path/hash to `[start_frame, end_frame]` or a list of ranges; each end is exclusive.

Filtering by people: If you’ve run face clustering, you can restrict results to frames containing specific people:

{
  "query": "waving hands",
  "cache_dir": "/Users/me/JumperAnalysis",
  "media_paths": ["/Videos/interview.mp4"],
  "people_filter_mode": "and",
  "people_filter": [
    {"cluster_job_name": "Interview Faces", "person_name": "Anna"},
    {"cluster_job_name": "Interview Faces", "person_name": "David"}
  ]
}

`POST /search/image`

Find moments visually similar to a reference image. Optionally combine with a text query. Example request:

curl -X POST http://localhost:6699/api/v1/search/image \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_path": "/Images/reference.jpg",
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_paths": ["/Videos/interview.mp4"],
    "max_results": 10
  }'

Parameters:

Parameter	Type	Default	Description
`image_path`	string	required	Path to the reference image
`query`	string	optional	Text query to combine with the image
`cache_dir`	string	required	Analysis data folder
`media_paths`	string[]	`[]`	Restrict to these files
`max_results`	int	50	Maximum matches to return
`search_all`	bool	false	Search all loaded media
`exclude`	string[]	`[]`	Visual concepts to softly push down in the ranking. Requires `query`.
`metadata_filter_request`	object	optional	Metadata filters from `/metadata/facets`
`segments_to_frame_indices`	object	optional	Selected media path/hash to one or more half-open 1 FPS frame ranges.

`POST /search/frame`

Find moments similar to a specific frame in a video — a “find more like this” search. Example request:

curl -X POST http://localhost:6699/api/v1/search/frame \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "media_path": "/Videos/interview.mp4",
    "time_seconds": 38,
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_paths": ["/Videos/interview.mp4"],
    "max_results": 10
  }'

Parameters:

Parameter	Type	Default	Description
`media_path`	string	required	Video to extract the reference frame from
`time_seconds`	number	required	Timestamp in seconds
`query`	string	optional	Text query to combine with the frame
`cache_dir`	string	required	Analysis data folder
`media_paths`	string[]	`[]`	Restrict to these files
`max_results`	int	50	Maximum matches to return
`search_all`	bool	false	Search all loaded media
`exclude`	string[]	`[]`	Visual concepts to softly push down in the ranking. Requires `query`.
`metadata_filter_request`	object	optional	Metadata filters from `/metadata/facets`
`segments_to_frame_indices`	object	optional	Selected media path/hash to one or more half-open 1 FPS frame ranges.

`POST /search/transcript`

Search through loaded transcriptions for segments containing a query string. Uses case-insensitive substring matching. To search only within one named transcript speaker, pass speaker or speaker_name. Example request:

curl -X POST http://localhost:6699/api/v1/search/transcript \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "hello world",
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_paths": ["/Videos/interview.mp4"],
    "search_all": false,
    "segments_to_time_ranges": {
      "/Videos/interview.mp4": [[10.0, 20.0], [300.0, 340.0]]
    },
    "speaker_name": "Anna",
    "max_results": 10
  }'

Response:

{
  "matches": [
    {
      "media_path": "/Videos/interview.mp4",
      "hash_str": "1e09e4953de0471b",
      "start_seconds": 12.5,
      "end_seconds": 15.2,
      "text": "And she said hello world to the audience",
      "start_timestamp": "00:00:12",
      "end_timestamp": "00:00:15",
      "speaker": "SPEAKER_00",
      "speaker_name": "Anna"
    }
  ]
}

Speaker filtering uses transcript speaker display names stored in transcription metadata. It is separate from face-clustering people names and does not use people_filter. Matches may also include media_type (audio or video) when Jumper can determine it. Parameters:

Parameter	Type	Default	Description
`query`	string	required	Text to search for (case-insensitive substring match)
`cache_dir`	string	required	Analysis data folder
`media_paths`	string[]	`[]`	Restrict to these files
`max_results`	int	50	Maximum matches to return
`search_all`	bool	true	Search across all loaded transcriptions
`speaker`	string	optional	Restrict results to a named transcript speaker
`speaker_name`	string	optional	Alias for `speaker`
`metadata_filter_request`	object	optional	Metadata filters from `/metadata/facets`. Defaults to a `speech` scope when omitted.
`segments_to_time_ranges`	object	optional	Selected media path/hash to `[start_seconds, end_seconds]` or a list of ranges; each end is exclusive. Segments are filtered before matching and `max_results`, and overlapping segments are included.

Transcriptions

`POST /transcriptions`

Returns speech transcriptions for media files that have been transcribed via /analyze. Example request:

curl -X POST http://localhost:6699/api/v1/transcriptions \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_paths": ["/Audio/voiceover.mp3", "/Videos/interview.mp4"]
  }'

Response:

{
  "transcriptions": {
    "/Audio/voiceover.mp3": [
      [0.0, " One, two, three, testing.", 2.52, "/Audio/voiceover.mp3"]
    ],
    "/Videos/interview.mp4": [
      [0.0, " Welcome to today's discussion.", 3.84, "/Videos/interview.mp4"],
      [3.84, " We'll be talking about...", 7.12, "/Videos/interview.mp4"]
    ]
  }
}

Each segment is an array: [start_seconds, text, end_seconds, media_path]. The response also includes transcription_data, a mapping keyed by media path for files with speaker metadata. Each entry contains segments in the same legacy array shape, hash_str, and speakers, a mapping of transcript-local IDs such as SPEAKER_00 to metadata containing zero-based segment_indices and an optional display name. Files without speaker metadata are omitted from transcription_data; the mapping is empty when no requested file has it. If the Analysis folder cannot be read, this endpoint returns HTTP 503. Files without available transcriptions are omitted from both mappings.

`POST /transcriptions/range`

Returns only transcript segments overlapping one half-open source time range. Prefer hash_str so Jumper can read the cached transcript without touching the source media file.

curl -X POST http://localhost:6699/api/v1/transcriptions/range \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "hash_str": "1e09e4953de0471b",
    "start_seconds": 120,
    "end_seconds": 180,
    "max_segments": 120
  }'

{
  "hash_str": "1e09e4953de0471b",
  "media_path": null,
  "transcript_status": "used",
  "start_seconds": 120.0,
  "end_seconds": 180.0,
  "segments": [
    {
      "id": "transcript_000018",
      "segment_index": 18,
      "start_seconds": 118.8,
      "end_seconds": 124.2,
      "text": "The segment crosses into the requested range.",
      "text_truncated": false,
      "speaker_ids": ["SPEAKER_00"],
      "speaker_names": ["Anna"]
    }
  ],
  "returned_segment_count": 1,
  "returned_character_count": 54,
  "remaining_segment_count": 0,
  "truncated": false,
  "text_truncated": false,
  "truncated_segment_indices": [],
  "next_after_segment_index": null
}

If truncated is true, repeat the same request with after_segment_index set to next_after_segment_index. max_segments defaults to 120 and must be an integer from 1 to 500; values outside that range return HTTP 400. Responses also use a fixed 24,000-character text budget. If one pathological source segment alone exceeds that budget, its text is truncated in place with an explicit marker; the segment reports text_truncated: true and original_character_count, while the response lists its index in truncated_segment_indices. Missing or empty transcripts return an empty segments array with transcript_status set to not_available or empty.

Thumbnails

`POST /thumbnails`

Get base64-encoded JPEG thumbnail images for specific media/timestamp pairs. Example request:

curl -X POST http://localhost:6699/api/v1/thumbnails \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "requests": [
      {"media_path": "/Videos/interview.mp4", "time_seconds": 38},
      {"media_path": "/Videos/interview.mp4", "time_seconds": 76}
    ]
  }'

Response:

{
  "thumbnails": [
    {"thumbnail": "/9j/4AAQSkZJRg..."},
    {"thumbnail": "/9j/4AAQSkZJRg..."}
  ]
}

Each thumbnail is a base64-encoded JPEG string, or null for audio files or when no frame could be retrieved.

`POST /thumbnails/scene`

Get a strip of thumbnails spanning a time range. Useful for timeline scrubbers. Example request:

curl -X POST http://localhost:6699/api/v1/thumbnails/scene \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_path": "/Videos/interview.mp4",
    "start_time": "00:01:00",
    "end_time": "00:02:00",
    "hash_str": "1e09e4953de0471b"
  }'

Response:

{
  "scene_thumbnails": [
    ["/9j/4AAQSkZJRg...", "00:01:00"],
    ["/9j/4AAQSkZJRg...", "00:01:01"],
    ["/9j/4AAQSkZJRg...", "00:01:02"]
  ]
}

Each entry is [base64_jpeg, timestamp]. For ranges longer than 100 seconds, Jumper samples 100 evenly-spaced frames instead of one per second. Shorter ranges include both integer-second endpoints. Audio files and still images return {"scene_thumbnails": null}.

Face Clustering

Jumper detects faces across video frames and automatically groups them by identity. These endpoints let you inspect, name, and refine those groups.

`GET /faces/clusters`

Lists all clustering jobs and their statistics. Example request:

curl -H "X-License-Key: YOUR_KEY" \
  "http://localhost:6699/api/v1/faces/clusters?cache_dir=/Users/me/JumperAnalysis"

Response:

{
  "cluster_jobs": ["Interview Faces"],
  "jobs": [
    {
      "name": "Interview Faces",
      "total_entries": 206,
      "num_clusters": 2,
      "noise_entries": 3,
      "cluster_ids": ["a1b2c3d4-...", "e5f6a7b8-..."],
      "face_storage_version": 2,
      "media_hashes": ["1e09e4953de0471b"]
    }
  ]
}

face_storage_version reports the on-disk face storage format for the job. Newer jobs use the packed format; older legacy jobs may not be mutable for reclustering or merges.

`POST /faces/clusters/samples`

Get sample face thumbnail images for each cluster. Useful for building a “who is this?” UI. Example request:

curl -X POST http://localhost:6699/api/v1/faces/clusters/samples \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "cluster_job_name": "Interview Faces",
    "limit_per_cluster": 4,
    "max_clusters": 50
  }'

Response:

{
  "cluster_job_name": "Interview Faces",
  "num_clusters": 2,
  "num_clusters_after_filter": 2,
  "total_entries": 206,
  "clusters": [
    {
      "cluster_id": "a1b2c3d4-...",
      "name": "Rodrigo",
      "size": 120,
      "sample_faces": ["/9j/4AAQ...", "/9j/4AAQ...", "/9j/4AAQ...", "/9j/4AAQ..."]
    },
    {
      "cluster_id": "e5f6a7b8-...",
      "name": "Carlos",
      "size": 83,
      "sample_faces": ["/9j/4AAQ...", "/9j/4AAQ...", "/9j/4AAQ...", "/9j/4AAQ..."]
    }
  ]
}

Parameters:

Parameter	Type	Default	Description
`cache_dir`	string	required	Analysis data folder
`cluster_job_name`	string	required	Which clustering job to query
`limit_per_cluster`	int	12	Max face thumbnails per cluster
`min_cluster_size`	int	1	Skip clusters smaller than this
`max_cluster_size`	int	1000000000	Skip clusters larger than this
`max_clusters`	int	100	Maximum clusters to return
`include_noise`	bool	false	Include unassigned faces in response

With include_noise: true, the response also includes noise_size and noise_sample (base64-encoded JPEGs). If the collection has no saved face data, HTTP 200 returns {"warning": "No face data available for this collection"}.

`POST /faces/clusters/faces`

Get paginated face images for specific cluster(s). For browsing all faces in a cluster. Supply cluster_id or a non-empty cluster_ids array. Pagination applies separately to each selected cluster. Example request:

curl -X POST http://localhost:6699/api/v1/faces/clusters/faces \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "cluster_job_name": "Interview Faces",
    "cluster_id": "a1b2c3d4-...",
    "limit": 100,
    "offset": 0
  }'

Parameters:

Parameter	Type	Default	Description
`cluster_id`	string	-	Single cluster to query
`cluster_ids`	string[]	-	Multiple clusters (a non-empty array overrides `cluster_id`)
`limit`	int	500	Page size per cluster, clamped to 1–2000
`offset`	int	0	Entries to skip per cluster, clamped to zero or greater

Response:

{
  "cluster_job_name": "Interview Faces",
  "clusters": [
    {
      "cluster_id": "a1b2c3d4-...",
      "size": 120,
      "available_faces": 2,
      "offset": 0,
      "limit": 100,
      "returned": 2,
      "has_more": false,
      "faces": ["/9j/4AAQ...", "/9j/4AAQ..."]
    }
  ]
}

faces contains base64-encoded JPEG images, not face entry IDs. size counts face detections; available_faces counts images available for pagination. If no saved cluster data is available, the response contains an empty clusters array and a warning.

`PUT /faces/clusters/names`

Assign human-readable names to clusters. Use an empty string or null as the name to clear an assignment. Example request:

curl -X PUT http://localhost:6699/api/v1/faces/clusters/names \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "cluster_job_name": "Interview Faces",
    "assignments": [
      {"cluster_id": "a1b2c3d4-...", "name": "Rodrigo"},
      {"cluster_id": "e5f6a7b8-...", "name": "Carlos"}
    ]
  }'

Response:

{
  "updated": 2,
  "changes": {
    "a1b2c3d4-...": "Rodrigo",
    "e5f6a7b8-...": "Carlos"
  }
}

`POST /faces/recluster`

Re-runs face clustering with different parameters. Useful for tuning how aggressively faces are grouped. Runs asynchronously. Returns HTTP 409 if another analysis task is running or the face collection uses read-only legacy storage. Legacy collections support reading and naming groups, but cannot be reclustered or modified with merges and moves. Example request:

curl -X POST http://localhost:6699/api/v1/faces/recluster \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "cluster_job_name": "Interview Faces",
    "eps": 0.55,
    "min_samples": 3
  }'

Response (202):

{
  "message": "Re-clustering started",
  "task_id": "f1e2d3c4-..."
}

Parameters:

Parameter	Type	Default	Description
`eps`	float	0.48	Clustering sensitivity — lower means stricter grouping (fewer, purer clusters)
`min_samples`	int	5	Minimum faces needed to form a cluster
`auto_detect_params`	bool	false	Let Jumper pick eps/min_samples automatically
`clear_names`	bool	false	Clear all existing cluster names

`POST /faces/clusters/modify`

Merge clusters or move individual faces between clusters. Useful for correcting mistakes. Legacy face collections return HTTP 409. Example — merge two clusters:

curl -X POST http://localhost:6699/api/v1/faces/clusters/modify \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "cluster_job_name": "Interview Faces",
    "merges": [
      {
        "cluster_ids": ["small-cluster-id", "target-cluster-id"],
        "target_cluster_id": "target-cluster-id"
      }
    ],
    "moves": []
  }'

A merge needs at least two existing cluster_ids. target_cluster_id is optional and must be one of those IDs. If omitted, Jumper prefers a named cluster, then the largest cluster. Each move has from_cluster_id, to_cluster_id, and entry_ids (face entry UUIDs). Both clusters must already exist. The face-image pagination endpoint does not return these entry IDs. Response:

{
  "merges": [
    {"target": "target-cluster-id", "sources": ["small-cluster-id"]}
  ],
  "moves": []
}

Applied moves return {"from": "source-cluster-id", "to": "target-cluster-id", "moved": 3}.

Watch Folders

Watch folders let Jumper automatically analyze new media files as they appear in a directory.

`GET /watch-folders`

Lists all configured watch folders and the background service status.

curl -H "X-License-Key: YOUR_KEY" http://localhost:6699/api/v1/watch-folders

Response:

{
  "watch_folders": [
    {
      "id": "wf-abc123",
      "folder_path": "/Volumes/Media/Ingest",
      "enabled": true,
      "enable_visual_analysis": true,
      "enable_audio_analysis": true,
      "enable_face_analysis": false,
      "audio_language": "english",
      "audio_channels": [],
      "qwen_model_variant": "more_accurate",
      "detect_speakers": true,
      "speaker_count": null,
      "cluster_job_name": null,
      "face_eps": 0.48,
      "face_min_samples": 5,
      "cache_dir": "/Users/me/JumperAnalysis",
      "excluded_extensions": [".jpg", ".jpeg"],
      "excluded_filename_globs": ["*_a04.mxf"],
      "excluded_folder_globs": ["finished", "client_a/finished_*"],
      "metadata_filter_request": {"filters": []},
      "created_at": 1707840000,
      "last_poll_time": 1707840060,
      "files_analyzed_count": 24
    }
  ],
  "service_status": {
    "state": "running",
    "current_folder": null,
    "current_file": null,
    "files_pending": 0,
    "files_processed_this_session": 24,
    "last_error": null,
    "paused_until": null,
    "folder_stats": {}
  }
}

`POST /watch-folders`

Add a new watch folder. The folder and any explicit cache_dir must exist on disk. Creating an enabled folder saves its configuration. If the watch-folder service is stopped, call /watch-folders/service/start to begin monitoring.

curl -X POST http://localhost:6699/api/v1/watch-folders \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_path": "/Volumes/Media/Ingest",
    "cache_dir": "/Users/me/JumperAnalysis",
    "enabled": true,
    "enable_visual_analysis": true,
    "enable_audio_analysis": true,
    "audio_language": "english",
    "audio_channels": [],
    "qwen_model_variant": "more_accurate",
    "detect_speakers": true,
    "speaker_count": "auto",
    "excluded_extensions": [".jpg", ".jpeg"],
    "excluded_filename_globs": ["*_a04.mxf"],
    "excluded_folder_globs": ["finished", "client_a/finished_*"]
  }'

Response (201):

{
  "message": "Watch folder added: /Volumes/Media/Ingest",
  "watch_folder": { ... }
}

Parameters:

Parameter	Type	Default	Description
`folder_path`	string	required	Absolute path to watch
`cache_dir`	string or null	optional	Existing Analysis folder; omitted or null uses the app’s default Analysis folder
`enabled`	bool	true	Include this folder when the watch-folder service is running
`enable_visual_analysis`	bool	true	Analyze visual content for searching
`enable_audio_analysis`	bool	false	Transcribe audio
`enable_face_analysis`	bool	false	Detect and cluster faces
`audio_language`	string	”english”	Language hint for transcription
`audio_channels`	array[int]	`[]`	1-based channels to transcribe; empty uses the default downmix to mono
`qwen_model_variant`	string	`"auto"`	`"faster"` (0.6B) or `"more_accurate"` (1.7B) for Qwen-supported languages
`detect_speakers`	bool	true	Run speaker detection after transcription
`speaker_count`	string or int	`"auto"`	Expected speakers: `"auto"`, `1`, `2`, `3`, `4`, or `"5+"`
`cluster_job_name`	string or null	-	Direct folder name; required if face analysis is enabled
`face_eps`	float	0.48	Clustering sensitivity for face grouping
`face_min_samples`	int	5	Minimum faces needed to form a cluster
`excluded_extensions`	array[string]	`[]`	File extensions to skip; normalized to lowercase with a leading dot
`excluded_filename_globs`	array[string]	`[]`	Filename-only glob patterns to skip, matched case-insensitively
`excluded_folder_globs`	array[string]	`[]`	Folder glob patterns to skip, matched case-insensitively under the watched folder
`metadata_filter_request`	object or null	`{"filters": []}`	Metadata filters that candidate files must match before analysis

metadata_filter_request.filters uses the same facet_id, operator, and values fields as search metadata filters. The scope is the watched folder’s candidate files; a supplied scope field is ignored. Set filters to [] or send null to clear these filters. excluded_filename_globs apply to the basename only, not the relative or absolute path. excluded_folder_globs entries without a path separator match any folder name; for example, finished skips files inside any folder named finished or Finished. Entries with / or \ match relative folder paths under the watched folder; for example, client_a/finished_* skips matching folders under client_a only. Backslashes are normalized to /. Path patterns match segment by segment, so */folder2/finished matches one parent folder above folder2, while folder2/finished matches only from the watch-folder root.

`PUT /watch-folders/{id}`

Update settings for an existing watch folder. Only include the fields you want to change. The settings above are supported except folder_path, which cannot be changed. Set cache_dir to null to restore the app’s default Analysis folder. Invalid analysis settings, exclusions, or a nonexistent/disallowed Analysis folder return HTTP 400. A missing watch-folder ID returns HTTP 404.

curl -X PUT http://localhost:6699/api/v1/watch-folders/wf-abc123 \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false, "excluded_extensions": [], "excluded_filename_globs": ["*_proxy.mov"], "excluded_folder_globs": ["finished", "client_a/finished_*"]}'

`DELETE /watch-folders/{id}`

Remove a watch folder. Does not delete any analysis data.

curl -X DELETE http://localhost:6699/api/v1/watch-folders/wf-abc123 \
  -H "X-License-Key: YOUR_KEY"

`POST /watch-folders/service/start`

Start the background service that monitors watch folders. This uses the enabled watch-folder configuration already stored in settings; it does not require prior UI interaction in the current session.

curl -X POST http://localhost:6699/api/v1/watch-folders/service/start \
  -H "X-License-Key: YOUR_KEY"

`POST /watch-folders/service/stop`

Request a stop of the background service. The request returns immediately and state may be "stopping" while current work finishes. Poll /watch-folders/service/status until state is "stopped".

curl -X POST http://localhost:6699/api/v1/watch-folders/service/stop \
  -H "X-License-Key: YOUR_KEY"

`GET /watch-folders/service/status`

Check if the service is running.

curl -H "X-License-Key: YOUR_KEY" \
  http://localhost:6699/api/v1/watch-folders/service/status

Response:

{
  "state": "running",
  "current_folder": null,
  "current_file": null,
  "files_pending": 0,
  "files_processed_this_session": 24,
  "last_error": null,
  "paused_until": null,
  "folder_stats": {}
}

Cache Paths

`POST /cache-paths`

Get the visual and audio cache folder paths for a specific media file. Useful for inspecting or managing analysis data on disk.

curl -X POST http://localhost:6699/api/v1/cache-paths \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_path": "/Videos/interview.mp4"
  }'

Response:

{
  "video_cache_path": "/Users/me/JumperAnalysis/1e09e4953de0471b",
  "audio_cache_path": "/Users/me/JumperAnalysis/1e09e4953de0471b_audio",
  "hash_str": "1e09e4953de0471b"
}

Paths are null if the corresponding cache folder does not exist.

Export

`POST /export/clips`

Export trimmed video clips to a folder using ffmpeg. Example request:

curl -X POST http://localhost:6699/api/v1/export/clips \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clips": [
      {
        "source_path": "/Videos/interview.mp4",
        "start_seconds": 10,
        "end_seconds": 25
      },
      {
        "source_path": "/Videos/interview.mp4",
        "start_seconds": 60,
        "end_seconds": 90,
        "subfolder": "highlights"
      }
    ],
    "output_dir": "/Users/me/Exports",
    "copy_codec": true
  }'

Response:

{
  "results": [
    {"success": true, "output_path": "/Users/me/Exports/clip_0000.mp4"},
    {"success": true, "output_path": "/Users/me/Exports/highlights/clip_0001.mp4"}
  ],
  "summary": "2/2 clips exported successfully"
}

Parameters:

Parameter	Type	Default	Description
`clips`	object[]	required	Array of clip definitions
`clips[].source_path`	string	required	Source media file path
`clips[].start_seconds`	number	required	Start time in seconds
`clips[].end_seconds`	number	required	End time in seconds
`clips[].subfolder`	string	optional	Subfolder within output_dir
`clips[].output_filename`	string	optional	Output filename; defaults to `clip_0000`, `clip_0001`, etc. with the source extension
`output_dir`	string	required	Directory to write clips to
`copy_codec`	bool	true	Stream copy (fast, no re-encode)

The endpoint returns HTTP 200 with a result for every clip, including individual export failures. Check each result’s success and error, as well as the summary.

`POST /export/premiere-xml`

Generate a Premiere Pro compatible XML sequence file (XMEML v4). Import it into Premiere Pro or another NLE that supports XMEML. Example request:

curl -X POST http://localhost:6699/api/v1/export/premiere-xml \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_name": "Interview Highlights",
    "clips": [
      {"source_path": "/Videos/interview.mp4", "start_seconds": 10, "end_seconds": 25, "fps": 23.976},
      {"source_path": "/Videos/interview.mp4", "start_seconds": 60, "end_seconds": 90, "fps": 23.976}
    ],
    "output_path": "/Users/me/Exports/highlights.xml",
    "timebase": 24,
    "ntsc": true
  }'

Response:

{
  "output_path": "/Users/me/Exports/highlights.xml",
  "clip_count": 2,
  "total_duration_seconds": 45.0
}

Parameters:

Parameter	Type	Default	Description
`sequence_name`	string	”Untitled Sequence”	Name of the sequence in the NLE
`clips`	object[]	required	Array of clip definitions
`clips[].source_path`	string	required	Source media file path
`clips[].start_seconds`	number	required	Start time in seconds
`clips[].end_seconds`	number	required	End time in seconds
`clips[].fps`	number	optional	Native source frame rate, used for source file metadata and NTSC inference
`clips[].fps_timebase` / `clips[].fps_ntsc`	int / bool	inferred from `fps`	Explicit source rate; both must be supplied to override inference
`clips[].source_duration_seconds`	number	inferred	Full source duration for XML file metadata; otherwise inferred from the greatest source out-point
`clips[].label`	string	source filename	Clip name in the NLE, defaulting to the source filename without its extension
`clips[].has_audio`	bool	inferred	For `track: "both"`, controls whether an audio placement is emitted; omitted values assume audio for non-image sources
`clips[].audio_channels` / `clips[].audio_sample_rate`	int	optional	Source channel count and sample rate in Hz; mono/stereo receive channel-aware XML track metadata
`clips[].track`	string	”both”	Stream selection: `video`, `audio`, or `both`
`clips[].track_index`	int	1	One-based destination track within the selected media kind
`clips[].video_track_index` / `clips[].audio_track_index`	int	`track_index`	Separate destination indices for linked video/audio placements
`clips[].timeline_start_seconds`	number	sequential	Absolute sequence position; omitted positions use the running length of sequential clips
`output_path`	string	required	Where to write the XML file
`timebase`	int	inferred	Nominal sequence timebase (e.g. 24, 25, 30); inferred from the first clip with `fps`, otherwise 24
`ntsc`	bool	inferred	Applies the NTSC 1000/1001 rate reduction to `timebase`; when omitted, inferred from the first clip with `fps`

total_duration_seconds is the exported sequence’s maximum end time after frame rounding, including gaps and overlapping tracks. Use track: "audio" for audio-only source files and track: "video" to place video without its audio.

`POST /export/transcript`

Export transcript segments to a file (TXT, CSV, DOCX, or PDF). Example request:

curl -X POST http://localhost:6699/api/v1/export/transcript \
  -H "X-License-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "segments": [
      [0.32, "Hello world.", 5.84],
      [5.84, "Another line.", 11.20]
    ],
    "format": "txt",
    "display_name": "My Transcript",
    "output_path": "/Users/me/Exports/transcript.txt"
  }'

Response:

{
  "output_path": "/Users/me/Exports/transcript.txt",
  "format": "txt",
  "row_count": 2
}

Parameters:

Parameter	Type	Default	Description
`segments`	array	required	List of `[start_seconds, text, end_seconds]` arrays, optionally with a fourth speaker display label
`format`	string	`"txt"`	Export format: `txt`, `csv`, `docx`, `pdf`
`display_name`	string	`"Transcript"`	Name shown in header/filename
`output_path`	string	Desktop, sanitized display name	Destination file path
`include_silences`	bool	`true`	Include silence gap rows between segments

When exporting rows returned by /transcriptions, remove their fourth media_path field or replace it with a speaker display label. Otherwise the exporter treats the media path as the speaker label. row_count counts the submitted segments and excludes inserted silence rows.

Error Format

Endpoint errors generally include an error field:

{"error": "Description of what went wrong"}

Authentication failures also include message with validation details. Enterprise policy denials return {"policy_error": "Reason the request was denied"}. Common status codes:

Code	Meaning
`400`	Bad request (missing or invalid parameters)
`401`	No license key provided
`403`	Supplied key could not be validated, lacks Pro entitlements, or an Enterprise policy denied the action
`404`	Resource not found (e.g. watch folder ID)
`409`	Conflicting analysis, preload, or face-storage operation
`500`	Server error
`503`	Required models or analysis resources are unavailable or still loading

SocketIO Progress Tracking

For long-running operations (/analyze, /faces/recluster), connect to the SocketIO server at http://localhost:6699 and join the room matching the returned task_id. In Socket.IO terms, emit join with the returned task_id, then listen for progress. Event: progress

{
  "progress": 45.5,
  "video_path": "/Videos/interview.mp4",
  "done": false,
  "type": "video"
}

Common fields:

progress — numeric percentage
video_path — the file currently being processed, or null for some clustering updates
done — true when the task is complete
type — "video" for visual analysis, "speech" for transcription
is_cluster_job — present for face-clustering progress
cluster_job_name — present for face-clustering progress
cluster_media_hashes — present on some clustering completion events

​Jumper Public API v1

​Authentication

​Typical Workflow

​Endpoints

​Health

​GET /health

​Models

​GET /models/loaded

​GET /models/available

​POST /models/load

​Media Metadata

​POST /media/metadata

​Analysis

​POST /analyze

​POST /analyze/cancel

​Hierarchical Summaries

​POST /summaries/collections

​POST /summaries/list

​POST /summaries/overview

​POST /summaries/node

​Analysis Data Management

​POST /analysis-data/load

​POST /analysis-data/load-for-media

​POST /analysis-data/load-transcriptions

​Metadata Filters

​POST /metadata/facets

​Search

​POST /search/text

​POST /search/image

​POST /search/frame

​POST /search/transcript

​Transcriptions

​POST /transcriptions

​POST /transcriptions/range

​Thumbnails

​POST /thumbnails

​POST /thumbnails/scene

​Face Clustering

​GET /faces/clusters

​POST /faces/clusters/samples

​POST /faces/clusters/faces

​PUT /faces/clusters/names

​POST /faces/recluster

​POST /faces/clusters/modify

​Watch Folders

​GET /watch-folders

​POST /watch-folders

​PUT /watch-folders/{id}

​DELETE /watch-folders/{id}

​POST /watch-folders/service/start

​POST /watch-folders/service/stop

​GET /watch-folders/service/status

​Cache Paths

​POST /cache-paths

​Export

​POST /export/clips

​POST /export/premiere-xml

​POST /export/transcript

​Error Format

​SocketIO Progress Tracking

Jumper Public API v1

Authentication

Typical Workflow

Endpoints

Health

`GET /health`

Models

`GET /models/loaded`

`GET /models/available`

`POST /models/load`

Media Metadata

`POST /media/metadata`

Analysis

`POST /analyze`

`POST /analyze/cancel`

Hierarchical Summaries

`POST /summaries/collections`

`POST /summaries/list`

`POST /summaries/overview`

`POST /summaries/node`

Analysis Data Management

`POST /analysis-data/load`

`POST /analysis-data/load-for-media`

`POST /analysis-data/load-transcriptions`

Metadata Filters

`POST /metadata/facets`

Search

`POST /search/text`

`POST /search/image`

`POST /search/frame`

`POST /search/transcript`

Transcriptions

`POST /transcriptions`

`POST /transcriptions/range`

Thumbnails

`POST /thumbnails`

`POST /thumbnails/scene`

Face Clustering

`GET /faces/clusters`

`POST /faces/clusters/samples`

`POST /faces/clusters/faces`

`PUT /faces/clusters/names`

`POST /faces/recluster`

`POST /faces/clusters/modify`

Watch Folders

`GET /watch-folders`

`POST /watch-folders`

`PUT /watch-folders/{id}`

`DELETE /watch-folders/{id}`

`POST /watch-folders/service/start`

`POST /watch-folders/service/stop`

`GET /watch-folders/service/status`

Cache Paths

`POST /cache-paths`

Export

`POST /export/clips`

`POST /export/premiere-xml`

`POST /export/transcript`

Error Format

SocketIO Progress Tracking