Jumper Public API - Jumper Docs

Jumper analyzes video, image, and audio files locally on the machine running the backend. The public API lets MAM systems, automation scripts, AI agents, and custom integrations use Jumper’s media analysis engine for semantic visual search, speech transcription, hierarchical summaries, thumbnails, face clustering, watch folders, and exports. Base URL: 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 except GET /health requires a Jumper Pro license key. Use the X-License-Key header when possible.

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

{
  "license_key": "YOUR_KEY",
  "cache_dir": "/Users/me/JumperAnalysis",
  "media_paths": []
}

Typical workflow

Check health

Verify the backend is running with GET /health.

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.

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.

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.

Load analysis data

Load all analysis data with POST /analysis-data/load, visual data for selected media with POST /analysis-data/load-for-media, or transcript-only data with POST /analysis-data/load-transcriptions.

Search and retrieve

Search visually, search transcripts, fetch transcriptions, get thumbnails, inspect face clusters, or export clips and transcripts.

Batch many files into one POST /analyze request when possible. Jumper loads ML models per analysis request, so one larger request is much faster than many one-file requests on the same backend.

Endpoint groups

Area	Endpoints
Health	`GET /health`
Models	`GET /models/loaded`, `GET /models/available`, `POST /models/load`
Media	`POST /media/metadata`
Analysis	`POST /analyze`, `POST /analyze/cancel`
Summaries	`POST /summaries/collections`, `POST /summaries/list`, `POST /summaries/overview`, `POST /summaries/node`
Analysis data	`POST /analysis-data/load`, `POST /analysis-data/load-for-media`, `POST /analysis-data/load-transcriptions`
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/{watch_folder_id}`, `DELETE /watch-folders/{watch_folder_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`

Important behavior notes

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

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

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

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, original_index, hash_str, and video_path.

Watch folder exclusions

Watch folders support excluded_extensions and excluded_filename_globs. Glob patterns match the filename only, not the full path.

Transcript exports

Use POST /export/transcript to export transcript segments to txt, csv, docx, or pdf.

Example requests

curl http://localhost:6699/api/v1/health

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": [{"path": "/Videos/interview.mp4", "language": "english"}]
  }'

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"},
      "footage_context": "An unscripted television episode about commercial fishing",
      "summary_objective": {
        "preset": "unscripted_story",
        "priority_hints": ["reveals_reversals", "conflict"]
      }
    }]
  }'

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
  }'

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]],
    "format": "txt",
    "display_name": "My Transcript"
  }'

Use the generated endpoint reference in the sidebar for request and response schemas.

​Canonical files

OpenAPI YAML

OpenAPI JSON

Markdown Reference

​Authentication

​Typical workflow

​Endpoint groups

​Important behavior notes

​Example requests

Canonical files

Authentication

Typical workflow

Endpoint groups

Important behavior notes

Example requests