API Reference - Jumper Docs

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. Base URL: http://localhost:6699/api/v1

Authentication

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

Header (recommended)
JSON body

Use the X-License-Key header:

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

Include license_key in the request body:

{"license_key": "your-key-here", "cache_dir": "/path", "media_paths": []}

The key is validated on the first request and cached for the session — subsequent requests with the same key skip the network check.

Status	Meaning
`401`	No license key provided
`403`	Key is valid but not a Pro license

401: {"error": "Authentication required", "message": "Provide license_key in request body or X-License-Key header"}
403: {"error": "Jumper Pro license required", "message": "The public API requires a Jumper Pro license"}

Key concepts

cache_dir

The folder where Jumper stores analysis data (visual analysis, transcriptions, face clusters). You choose this path when running analysis or loading data.

media_paths

Absolute filesystem paths to media files. Jumper needs direct access to these files on the machine running the backend.

hash_str

A CRC32-based hash that uniquely identifies a media file. Returned by the metadata endpoint and used in other endpoints for efficient lookups.

model_key

Internal identifier for a visual or speech analysis model variant (e.g. v2-medium-256, mlx-large-v3-turbo).

Typical workflow

Most integrations follow this pattern:

Check health

Verify the backend is running with GET /health (no authentication required).

Analyze media

Run visual and/or speech analysis on your files via POST /analyze. Returns a task_id for progress tracking.

Load analysis data

Load analysis results into memory for searching with POST /analysis-data/load or POST /analysis-data/load-for-media.

Find matching moments by text, image, or frame similarity using the /search/* endpoints.

Get transcriptions

Retrieve speech-to-text results via POST /transcriptions.

Get thumbnails

Fetch preview images for specific timestamps with POST /thumbnails or POST /thumbnails/scene.

Example requests

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

Error format

All errors follow the same structure:

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

Code	Meaning
`400`	Bad request (missing or invalid parameters)
`401`	No license key provided
`403`	Not a Pro license
`404`	Resource not found (e.g. watch folder ID)
`500`	Server error
`503`	Models still loading — retry shortly

SocketIO progress tracking

For long-running operations (POST /analyze, POST /faces/recluster), connect to the SocketIO server at http://localhost:6699 and join the room matching the returned task_id.Event: progress

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

The type field indicates what’s being processed: "video" for visual analysis, "speech" for transcription. When done is true, the task is complete.

Endpoint reference

Use the sidebar to browse the full API reference. Endpoints are grouped by area:

Health — GET /health
Models — Load, list, and switch analysis models
Media — Metadata for media files
Analysis — Run analysis, cancel, load/clear data
Search — Text, image, frame, and transcript search
Transcriptions — Retrieve speech-to-text results
Thumbnails — Single frames and scene strips
Face Clustering — Clusters, samples, names, modify, recluster
Watch Folders — Automatic analysis on new files
Export — Clips and Premiere Pro XML

Jumper

Learn more at getjumper.io

​Authentication

​Key concepts

​Typical workflow

​Example requests

​Error format

​Endpoint reference

Jumper

Authentication

Key concepts

Typical workflow

Example requests

Error format

Endpoint reference