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

# Upgrade a face collection to the current storage format

> Upgrades a face collection whose face_storage_version is v2 to v3. This is needed once
before such a collection can be named, reclustered, modified or added to.
Runs asynchronously — returns a task_id for progress tracking. The progress events carry
is_face_collection_upgrade and end with either done=true and an upgrade summary, or an error.

Every face, group, name and ID is kept. Nothing of the collection is changed before the
last step, so a failed or cancelled upgrade leaves it as it was. The previous data files
are kept in `people/<cluster_job_name>/old-format-backup/` for 14 days. Computers running
an older Jumper version cannot use the collection until they update.




## OpenAPI

````yaml /api-reference/openapi-v1.yaml post /faces/upgrade
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, face detection with clustering, and hierarchical
    summaries.

    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. A non-empty JSON `license_key` takes

    precedence over the header.


    Send the raw license key on every authenticated request. Activating Jumper

    in the UI does not authenticate later API requests automatically. Pro uses

    the same entitlements in the UI and API; no separate API entitlement is
    needed.


    Missing keys return `401`. Supplied keys that cannot be validated or lack

    Pro entitlements return `403`. The `error` is `Jumper Pro license required`

    for both cases; inspect the response `message` for the validation reason.

    A valid non-Pro key can have `message: "OK"` and still return `403`.


    Enterprise policy denials also return `403`, with a `policy_error` field

    instead of `error`. Jumper checks the policy before the license key, so a

    denied request gets `403` even without a key.


    Successful validation is cached for 10 minutes. Health only checks

    connectivity and does not validate a license.


    Any valid Pro key works, even when the Jumper app is signed in with a

    different license.


    ## Requests


    Send POST and PUT bodies as a JSON object with `Content-Type:
    application/json`.

    Another content type, or JSON that isn't an object, returns `400`.


    Fields documented as booleans take only JSON `true` or `false`, and numbers
    only

    JSON numbers. Anything else, such as the string `"false"`, returns `400`
    with an

    `error` that names the field, for example `copy_codec must be true or
    false`.


    The API only accepts requests from the machine running Jumper. Use

    `localhost` or `127.0.0.1`. Requests from other machines get `404` with

    `{"error": "Not found"}`.


    ## Key Concepts


    - **`cache_dir`** — The folder where Jumper stores analysis data (visual
    analysis, transcriptions, face clusters). You choose this path.
      Analysis can write to any folder, but loading data into memory, searching, and face edits only work in the
      active Analysis folder. Read or change it with `/analysis-folder`; other folders return `409`.
    - **`media_paths`** — Absolute filesystem paths to media files. Jumper needs
    direct access to these files.

    - **`hash_str`** — A backend-issued media identity returned by the metadata
    endpoint. Computed with xxh64 from the file size and sampled head/tail
    bytes; it is not a full-file integrity checksum.

    - **`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:
  /faces/upgrade:
    post:
      tags:
        - Face Clustering
      summary: Upgrade a face collection to the current storage format
      description: >
        Upgrades a face collection whose face_storage_version is v2 to v3. This
        is needed once

        before such a collection can be named, reclustered, modified or added
        to.

        Runs asynchronously — returns a task_id for progress tracking. The
        progress events carry

        is_face_collection_upgrade and end with either done=true and an upgrade
        summary, or an error.


        Every face, group, name and ID is kept. Nothing of the collection is
        changed before the

        last step, so a failed or cancelled upgrade leaves it as it was. The
        previous data files

        are kept in `people/<cluster_job_name>/old-format-backup/` for 14 days.
        Computers running

        an older Jumper version cannot use the collection until they update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - cache_dir
                - cluster_job_name
              properties:
                cache_dir:
                  type: string
                cluster_job_name:
                  type: string
                progress_room_id:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{8,64}$
                  description: >-
                    A Socket.IO room the client has already joined. Progress is
                    sent there and the room is returned as task_id, so an
                    upgrade that fails within moments is still heard. Without
                    it, or when it doesn't match the pattern, Jumper makes a
                    room.
                allow_missing_names:
                  type: boolean
                  default: false
                  description: >-
                    Upgrade a collection whose file with the names of its people
                    is damaged without those names. Without it such an upgrade
                    ends with an error event that has names_unreadable set to
                    true. Names that can be read are always kept.
      responses:
        '200':
          description: The collection is already in the current format
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  face_storage_version:
                    type: string
        '202':
          description: Upgrade started
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  task_id:
                    type: string
        '400':
          description: Invalid or missing cache_dir or collection name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/AuthenticationRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No such face collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            cache_dir is not the active Analysis folder (the response then
            includes active_cache_dir), or another analysis task is running, or
            faces are being analyzed into the collection, or the collection's
            face_storage_version is v1 and it cannot be upgraded.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Error'
                  - $ref: '#/components/schemas/InactiveAnalysisFolderError'
        '500':
          description: Unexpected failure while processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: >
        Jumper's endpoints return `error`. Authentication failures add
        `message`.

        Errors from the HTTP layer have only `message`. Examples: an unknown
        path

        (`404`), a wrong method (`405`), and unexpected server errors (`500`).
      properties:
        error:
          type: string
          description: Error message. Present on errors returned by Jumper's endpoints.
        message:
          type: string
          description: >-
            Validation detail on authentication failures, or the only field on
            HTTP-layer errors.
    InactiveAnalysisFolderError:
      type: object
      required:
        - error
        - active_cache_dir
      properties:
        error:
          type: string
          example: >-
            cache_dir is not the active Analysis folder. Change it with POST
            /api/v1/analysis-folder first.
        active_cache_dir:
          type: string
          description: The active Analysis folder
          example: /Users/me/JumperAnalysis
    PolicyError:
      type: object
      required:
        - policy_error
      properties:
        policy_error:
          type: string
          description: Enterprise policy restriction that denied the request.
  responses:
    AuthenticationRequired:
      description: >-
        No license key was supplied in X-License-Key or the JSON license_key
        field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Authentication required
            message: Provide license_key in request body or X-License-Key header
    Forbidden:
      description: >-
        The supplied key could not be validated, lacks Pro entitlements, or an
        Enterprise policy denied the action or the Analysis folder. Inspect
        message or policy_error for the reason.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/PolicyError'
          examples:
            invalidKey:
              summary: License key does not exist
              value:
                error: Jumper Pro license required
                message: >-
                  License invalid and activation not required: license does not
                  exist
            nonProKey:
              summary: Valid license without Pro entitlements
              value:
                error: Jumper Pro license required
                message: OK
            policyDenied:
              summary: Enterprise policy denied the action
              value:
                policy_error: >-
                  This action is not available under your organization's Jumper
                  policy
            policyFolderDenied:
              summary: Enterprise policy does not allow this Analysis folder
              description: >-
                Returned when `cache_dir` is outside the folders your
                organization allows. Endpoints that need a policy-controlled
                feature check the configured Analysis folder when the request
                has no `cache_dir`.
              value:
                policy_error: This Analysis folder is not allowed by your organization
  securitySchemes:
    HeaderAuth:
      type: apiKey
      in: header
      name: X-License-Key
      description: >-
        Raw Jumper Pro license key on every authenticated request, without a
        Bearer prefix

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.