> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getjumper.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Jumper Public API

> Overview of the Jumper Public API v1, with direct links to the canonical OpenAPI YAML and full Markdown reference for agents and integration tooling.

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, thumbnails, face clustering, watch folders, and exports.

**Base URL:** `http://localhost:6699/api/v1`

Canonical Jumper Public API v1 resources for scraping or inspection:

* Raw OpenAPI YAML: `/api-reference/openapi-v1.yaml`
* Raw OpenAPI JSON: `/api-reference/openapi.json`
* Markdown endpoint guide: `/api-reference/public-api-v1.md`
* Site-wide discovery files: `/llms.txt` and `/llms-full.txt`

Prefer the raw OpenAPI YAML or JSON for endpoint paths, request schemas, response schemas, and auth. Use the Markdown endpoint guide for workflow notes, examples, and behavior details that are easier to read as prose.

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

<Columns cols={2}>
  <Card title="OpenAPI YAML" icon="file-code" href="/api-reference/openapi-v1.yaml">
    Raw OpenAPI 3.0 contract for endpoint discovery, schemas, and generated clients.
  </Card>

  <Card title="OpenAPI JSON" icon="braces" href="/api-reference/openapi.json">
    Raw JSON mirror of the OpenAPI contract.
  </Card>
</Columns>

<Card title="Markdown Reference" icon="file-text" href="/api-reference/public-api-v1.md">
  Markdown export with examples, workflow notes, and endpoint behavior.
</Card>

## Authentication

Every endpoint except `GET /health` requires a **Jumper Pro** license key. Use the `X-License-Key` header when possible.

<CodeGroup>
  ```bash Header theme={null}
  curl -H "X-License-Key: YOUR_KEY" http://localhost:6699/api/v1/models/loaded
  ```

  ```json Body theme={null}
  {
    "license_key": "YOUR_KEY",
    "cache_dir": "/Users/me/JumperAnalysis",
    "media_paths": []
  }
  ```
</CodeGroup>

## Typical workflow

<Steps>
  <Step title="Check health">
    Verify the backend is running with `GET /health`.
  </Step>

  <Step title="Analyze media">
    Run visual analysis, transcription, and optional face clustering with `POST /analyze`.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Search and retrieve">
    Search visually, search transcripts, fetch transcriptions, get thumbnails, inspect face clusters, or export clips and transcripts.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="Watch folder exclusions">
    Watch folders support `excluded_extensions` and `excluded_filename_globs`. Glob patterns match the filename only, not the full path.
  </Accordion>

  <Accordion title="Transcript exports">
    Use `POST /export/transcript` to export transcript segments to `txt`, `csv`, `docx`, or `pdf`.
  </Accordion>
</AccordionGroup>

## Example requests

<CodeGroup>
  ```bash Health theme={null}
  curl http://localhost:6699/api/v1/health
  ```

  ```bash Analyze theme={null}
  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"}]
    }'
  ```

  ```bash Text search theme={null}
  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
    }'
  ```

  ```bash Export transcript theme={null}
  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"
    }'
  ```
</CodeGroup>

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