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

# Create a watch folder

> Adds a new folder to be automatically analyzed when new media files appear.
The folder must exist on disk. Exclusion glob patterns are matched against
the filename only, not the full path.




## OpenAPI

````yaml /api-reference/openapi-v1.yaml post /watch-folders
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:
  /watch-folders:
    post:
      tags:
        - Watch Folders
      summary: Create a watch folder
      description: >
        Adds a new folder to be automatically analyzed when new media files
        appear.

        The folder must exist on disk. Exclusion glob patterns are matched
        against

        the filename only, not the full path.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - folder_path
              properties:
                folder_path:
                  type: string
                  description: Absolute path to the folder to watch
                cache_dir:
                  type: string
                  description: >-
                    Where to store analysis results (optional, uses default if
                    omitted)
                enabled:
                  type: boolean
                  default: true
                enable_visual_analysis:
                  type: boolean
                  default: true
                enable_audio_analysis:
                  type: boolean
                  default: false
                enable_face_analysis:
                  type: boolean
                  default: false
                audio_language:
                  type: string
                  default: english
                cluster_job_name:
                  type: string
                  description: Required when face analysis is enabled
                face_eps:
                  type: number
                  default: 0.48
                face_min_samples:
                  type: integer
                  default: 5
                excluded_extensions:
                  type: array
                  description: >-
                    File extensions to skip, normalized to lowercase with a
                    leading dot
                  items:
                    type: string
                excluded_filename_globs:
                  type: array
                  description: >-
                    Case-insensitive glob patterns matched against the filename
                    only
                  items:
                    type: string
                excluded_folder_globs:
                  type: array
                  description: >-
                    Case-insensitive folder glob patterns under the watched
                    folder. Patterns with slashes match relative folder paths
                    segment by segment.
                  items:
                    type: string
      responses:
        '201':
          description: Watch folder created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  watch_folder:
                    $ref: '#/components/schemas/WatchFolder'
        '400':
          description: Folder doesn't exist or already registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    WatchFolder:
      type: object
      properties:
        id:
          type: string
        folder_path:
          type: string
        enabled:
          type: boolean
        enable_visual_analysis:
          type: boolean
        enable_audio_analysis:
          type: boolean
        enable_face_analysis:
          type: boolean
        audio_language:
          type: string
        cluster_job_name:
          type: string
          nullable: true
        face_eps:
          type: number
        face_min_samples:
          type: integer
        cache_dir:
          type: string
          nullable: true
        excluded_extensions:
          type: array
          description: File extensions to skip, normalized to lowercase with a leading dot
          items:
            type: string
        excluded_filename_globs:
          type: array
          description: Case-insensitive glob patterns matched against the filename only
          items:
            type: string
        excluded_folder_globs:
          type: array
          description: >-
            Case-insensitive folder glob patterns under the watched folder.
            Patterns with slashes match relative folder paths segment by
            segment.
          items:
            type: string
        created_at:
          type: number
        last_poll_time:
          type: number
        files_analyzed_count:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
  securitySchemes:
    HeaderAuth:
      type: apiKey
      in: header
      name: X-License-Key
      description: Jumper Pro license key passed via header

````