> ## 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. # Search by reference image > Finds moments visually similar to a reference image. Optionally combine with a text query to refine results. Results are ordered best-first. ## OpenAPI ````yaml /api-reference/openapi-v1.yaml post /search/image openapi: 3.0.3 info: title: Jumper Public API version: '1.0' description: > REST API for third-party integrations with Jumper's media analysis engine. Jumper analyzes video, image, and audio files — enabling semantic visual search, speech transcription, and face detection with clustering. This API exposes those capabilities for use by MAM systems, automation pipelines, and custom tooling. ## Authentication All endpoints except `/health` require a **Jumper Pro** license key. The OpenAPI contract models the supported `X-License-Key` header flow. Jumper also accepts a `license_key` field in many JSON POST bodies as a convenience, but that is a Jumper-specific request-body convention rather than an OpenAPI security scheme. Invalid or missing keys return `401`. Non-Pro keys return `403`. ## Key Concepts - **`cache_dir`** — The folder where Jumper stores analysis data (visual analysis, transcriptions, face clusters). You choose this path. - **`media_paths`** — Absolute filesystem paths to media files. Jumper needs direct access to these files. - **`hash_str`** — A CRC32-based hash that uniquely identifies a media file. Returned by the metadata endpoint. - **`model_key`** — Internal identifier for a visual or speech analysis model variant (e.g. `v2-medium-256`). contact: name: Jumper url: https://getjumper.io servers: - url: http://localhost:6699/api/v1 description: Local Jumper backend security: - HeaderAuth: [] paths: /search/image: post: tags: - Search summary: Search by reference image description: | Finds moments visually similar to a reference image. Optionally combine with a text query to refine results. Results are ordered best-first. requestBody: required: true content: application/json: schema: type: object required: - image_path - cache_dir properties: image_path: type: string description: Absolute path to the reference image query: type: string description: Optional text query to combine with the image exclude: type: array items: type: string description: >- Softly push down results that match these visual concepts. Requires query text. cache_dir: type: string media_paths: type: array items: type: string max_results: type: integer default: 50 search_all: type: boolean default: false metadata_filter_request: $ref: '#/components/schemas/MetadataFilterRequest' responses: '200': description: Search results ordered by visual similarity content: application/json: schema: type: object properties: matches: type: array items: $ref: '#/components/schemas/SearchMatch' components: schemas: MetadataFilterRequest: type: object properties: scope: $ref: '#/components/schemas/MetadataFilterScope' filters: type: array items: $ref: '#/components/schemas/MetadataFilter' default: [] description: > Metadata filters to apply to a search. If scope is omitted, Jumper derives it from the endpoint's `search_all` and `media_paths` values. SearchMatch: type: object properties: frame_idx: type: string description: >- Frame number within the media file (1 FPS basis), returned as a string timestamp: type: string description: Timestamp as HH:MM:SS image: type: string format: byte description: Base64-encoded JPEG preview for the matched frame scene_start_timestamp: type: string description: Start of the matched scene as HH:MM:SS scene_end_timestamp: type: string description: End of the matched scene as HH:MM:SS original_index: type: integer description: Position in the underlying ranking before per-video grouping hash_str: type: string description: Hash of the media file this match belongs to video_path: type: string description: Absolute path to the media file required: - frame_idx - timestamp - image - scene_start_timestamp - scene_end_timestamp - original_index - hash_str - video_path MetadataFilterScope: type: object properties: mode: type: string enum: - paths - global default: paths description: >- `paths` scopes filters to the supplied files; `global` scopes to loaded searchable media. media_type: type: string enum: - visual - speech - any default: any description: Searchable media type for the scope. media_paths: type: array items: type: string description: >- Absolute media paths. When paired with `hash_strs`, the arrays are index-aligned. hash_strs: type: array items: type: string description: >- Media hashes aligned with `media_paths`, or standalone hashes for already-known media. expected_count: type: integer description: Optional count used for coverage reporting. MetadataFilter: type: object required: - facet_id - values properties: facet_id: type: string description: >- Facet identifier returned by `/metadata/facets`, such as `video.codec`. operator: type: string enum: - is_any_of - is_not - include_any_of - include_all_of - exclude_any_of - exclude_all_of - before - after - greater_than - less_than default: is_any_of values: type: array items: type: string description: Selected facet option values. securitySchemes: HeaderAuth: type: apiKey in: header name: X-License-Key description: Jumper Pro license key passed via header ````