# Update fields of the default config

Endpoint: PATCH /persist/configs/default
Version: 2.0.0
Security: engineBasic

## Header parameters:

  - `If-Match` (string, required)
    ETag of the revision this write is based on. * is not supported: quoting "any revision" defeats the concurrency check and is rejected with 412.

## Request fields (application/merge-patch+json):

  - `config` (object)
    The baseline settings every stream inherits before any group or override applies.

  - `config.active` (boolean)
    Whether analysis runs, for every stream that does not say otherwise.

  - `config.listeners` (object)
    Listeners, keyed by name, applied to every stream that does not override them.

  - `config.processing` (object)
    Frame sampling and shipping settings applied to every stream that does not override them.

  - `config.processing.inference_fps` (integer)
    Frames per second sent to analysis; -1 matches the source rate. Default -1.

  - `config.processing.window_seconds` (number)
    Seconds per analysis window (scene/VLM/synthetic). Default 2.

  - `config.processing.video_height` (integer)
    Resize frames to this height; -1 matches source, 0 matches the model. Default 0.

  - `config.processing.grayscale` (boolean)
    Send frames in grayscale. Default false.

  - `config.processing.frame_source` (string)
    Capture frames via the transcoder or periodic frame grabs. Default transcoder, except the synthetic detector, which taps the source packets and defaults to grab.
    Enum: "transcoder", "grab"

  - `config.processing.grab_interval_seconds` (number)
    Frame-grab period when frame_source is grab. Default 1.

  - `config.processing.buffer_frames` (integer)
    Frames buffered awaiting processing. Sized from the incoming video by default.

  - `config.processing.auto_throttle` (boolean)
    Reduce inference_fps automatically when inference falls behind. Default off.

  - `config.processing.catch_up` (object,null)
    Scene/VLM — skip stale backlog to the live edge when inference lags.

  - `config.processing.catch_up.enabled` (boolean)
    Default true.

  - `config.processing.catch_up.max_behind_seconds` (number)
    Default is the buffer's own headroom.

  - `config.processing.rollup_interval_seconds` (number)
    How long detections are held for batch/rollup listener events. Default 2.

  - `config.processing.gpu_ids` (array,null)
    Pin VIS-side inference to these GPUs; null lets VIS balance.

  - `config.service` (object)
    Which Video Intelligence Service analyzes streams that do not override it.

  - `config.service.url` (string)
    VIS WebSocket endpoint, e.g. ws://vis-host:5001/ws/stream/.

  - `config.service.api_key` (string,null)
    Never echoed by a read. On a write: absent or null keeps the stored value, an empty string clears it.

  - `config.service.model_idle_timeout_seconds` (integer,null)
    How long VIS keeps an idle model loaded.

  - `config.diagnostics` (object)
    Debug aids applied to every stream that does not override them.

  - `config.diagnostics.save_images` (boolean)
    Save captured frames to disk on the Engine host. Default false.

  - `config.diagnostics.timing_log_seconds` (integer)
    Seconds between timing-metric dumps; 0 disables. Default 0.

  - `config.diagnostics.max_logged_messages` (integer)
    Protocol messages logged; -1 all, 0 disabled. Default 20.

  - `detectors` (object)
    Detector baselines for every type at once: a stream inherits the entry matching its own detector type. The default config selects no type, which is why these sit beside config rather than in it: config.detector selects one, and this document is the one that cannot.

  - `detectors.scene` (object,null)
    The analysis running on a stream. type selects the subtype; a patch that changes
it replaces the whole detector section.

  - `detectors.scene.type` (string, required)
    Detector subtype: scene, object, vlm, or synthetic.
    Enum: "scene", "object", "vlm", "synthetic"

  - `detectors.scene.classes` (array)
    Scene classes to detect.

  - `detectors.scene.sensitivity` (integer)
    Higher detects more; per-class overrides in class_sensitivity. Default 5.

  - `detectors.scene.class_sensitivity` (object)
    Per-class sensitivity overrides, keyed by class name; unlisted classes use sensitivity.

  - `detectors.scene.min_confidence` (number)
    Detections below this confidence are dropped. Default 0.3.

  - `detectors.scene.baseline` (object)
    The class set frame scores are normalized against.

  - `detectors.scene.baseline.set` (string,null)
    Named baseline: DEFAULT is ~1560 general scenes, TRAFFIC ~190 traffic scenes. Null falls back to custom_classes.
    Enum: "DEFAULT", "TRAFFIC"

  - `detectors.scene.baseline.custom_classes` (array,null)
    Baseline classes given outright, used when set is null. Enough of them to describe what the camera normally sees, or scores normalize against too little.

  - `detectors.object` (object,null)
    The analysis running on a stream. type selects the subtype; a patch that changes
it replaces the whole detector section.

  - `detectors.object.classes` (array,null)
    Classes to report; null reports all model classes.

  - `detectors.object.model` (string)
    Model variant. Ignored when checkpoint_path is set. Default medium.
    Enum: "nano", "small", "medium", "large"

  - `detectors.object.checkpoint_path` (string,null)
    Custom model weights on the VIS host; overrides model.

  - `detectors.object.tracking` (object,null)
    Absent or null inherits; {"method": "none"} turns tracking off.

  - `detectors.object.tracking.method` (string, required)
    byte-track assigns persistent IDs; none reports each frame's detections on their own. The remaining members apply to byte-track only.
    Enum: "byte-track", "none"

  - `detectors.object.tracking.min_confidence_to_create` (number)
    Confidence needed for a detection to start a new track.

  - `detectors.object.tracking.min_consecutive_frames` (integer)
    Frames an object must persist before its track becomes visible.

  - `detectors.object.tracking.min_overlap` (number)
    Overlap fraction for consecutive detections to match a track.

  - `detectors.object.tracking.max_lost_frames` (integer)
    Frames a track survives without detections.

  - `detectors.object.tracking.ignore_untracked` (boolean)
    Drop detections that have no track.

  - `detectors.object.tiling` (object,null)
    Absent or null inherits; {"mode": "none"} turns tiling off.

  - `detectors.object.tiling.mode` (string, required)
    none runs no tiling; fixed runs one grid per frame; gated runs probe + coarse + fine grids.
    Enum: "none", "fixed", "gated"

  - `detectors.object.tiling.min_grid` (object)
    Grid size and shape for the coarse/probe pass in gated mode.

  - `detectors.object.tiling.min_grid.rows` (integer, required)
    Number of tile rows.

  - `detectors.object.tiling.min_grid.cols` (integer, required)
    Number of tile columns.

  - `detectors.object.tiling.max_grid` (object)
    Grid size and shape for the full-resolution tiling pass. Required for every mode but none.

  - `detectors.object.tiling.tile_coverage_cutoff` (number)
    Drop tile detections covering more than this fraction of the tile; 1.0 disables.

  - `detectors.object.tiling.full_frame_pass` (boolean)
    fixed mode: also run a full-frame pass for objects larger than a tile.

  - `detectors.object.tiling.cluster_suppression_min_children` (integer)
    Drop a detection containing at least this many smaller ones; 0 disables.

  - `detectors.vlm` (object,null)
    The analysis running on a stream. type selects the subtype; a patch that changes
it replaces the whole detector section.

  - `detectors.vlm.endpoint` (object,null)
    Null inherits from the default config, and then the built-in http://vlm.docker:8000/v1 with Qwen/Qwen3-VL-4B-Instruct-FP8.

  - `detectors.vlm.endpoint.url` (string,null)
    OpenAI-compatible endpoint, e.g. http://vlm.docker:8000/v1.

  - `detectors.vlm.endpoint.model` (string,null)
    Model name to request from the endpoint.

  - `detectors.vlm.endpoint.timeout_seconds` (number)
    Request timeout, in seconds.

  - `detectors.vlm.endpoint.max_concurrent_requests` (integer)
    Maximum requests sent to the endpoint at once.

  - `detectors.vlm.mode` (string, required)
    Which analysis family runs. Only the matching block below applies.
    Enum: "detect", "describe", "custom"

  - `detectors.vlm.detect` (object,null)
    Settings for mode: detect; applies only when mode is detect.

  - `detectors.vlm.detect.classes` (array, required)
    Classes to look for.

  - `detectors.vlm.detect.class_hints` (object,null)
    Per-class hints inlined into the prompt; keys must be members of classes.

  - `detectors.vlm.detect.reasoning_level` (string,null)
    Built-in prompt preset VIS applies server-side: low and medium select its own prompt pairs plus a per-class boolean schema; high or absent uses the default class-aware prompts.
    Enum: "low", "medium", "high"

  - `detectors.vlm.custom` (object,null)
    Settings for mode: custom; applies only when mode is custom.

  - `detectors.vlm.custom.prompt` (object,null)
    Caller-authored prompt; null uses the endpoint's own default prompt.

  - `detectors.vlm.custom.prompt.system` (string,null)
    System prompt text.

  - `detectors.vlm.custom.prompt.user` (string,null)
    User prompt text.

  - `detectors.vlm.custom.response_schema` (object,null)
    JSON Schema forwarded verbatim to the endpoint.

  - `detectors.vlm.custom.classes` (array)
    Classes expanded into the {class_list} placeholder wherever either prompt uses it. Optional, and not a class list the analysis service filters on: in this mode the prompt decides what the model is asked, and these only render into it.

  - `detectors.vlm.custom.class_hints` (object,null)
    Per-class hints inlined into {class_list}; keys must be members of classes.

  - `detectors.vlm.generation` (object,null)
    Sampling parameters shared across every mode.

  - `detectors.vlm.generation.temperature` (number,null)
    Sampling temperature passed to the endpoint.

  - `detectors.vlm.generation.max_tokens` (integer,null)
    Maximum tokens the endpoint may generate.

  - `detectors.synthetic` (object,null)
    The analysis running on a stream. type selects the subtype; a patch that changes
it replaces the whole detector section.

  - `detectors.synthetic.endpoint` (object,null)
    Absent or null inherits from the default config.

  - `detectors.synthetic.endpoint.address` (string,null)
    gRPC host:port (not an http URL), e.g. svd.docker:8001.

  - `detectors.synthetic.endpoint.tls` (object,null)
    TLS settings for the connection; null auto-detects.

  - `detectors.synthetic.endpoint.tls.enabled` (boolean,null)
    Force TLS on or off; null auto-detects from the port and configured material.

  - `detectors.synthetic.endpoint.tls.ca_cert` (string,null)
    Path to the CA certificate on the VIS host, not the certificate itself (e.g. /certs/ca-cert.pem). Needed when the endpoint presents a private-CA certificate.

  - `detectors.synthetic.endpoint.tls.client_cert` (string,null)
    Path to the client certificate on the VIS host, for mutual TLS. Set it together with client_key; one without the other does not authenticate.

  - `detectors.synthetic.endpoint.tls.client_key` (string,null)
    Never echoed by a read. On a write: absent or null keeps the stored value, an empty string clears it.

  - `detectors.synthetic.endpoint.function_id` (string,null)
    NVIDIA Cloud Function ID, when the endpoint is served through NVCF.

  - `detectors.synthetic.classification_threshold` (number)
    Verdict is synthetic when the score exceeds this.

  - `etag` (string,null)
    This document's revision, to quote as If-Match on a write. Carried on the document; a read repeats it in the ETag header. Server-assigned and ignored on a write.

  - `concurrent_executions` (object)
    Parallel model instances per detector kind on VIS. The consumed kinds are object_detection and scene_detection; any other key is a 400 rather than silently dropped.

## Response 200 fields (application/json):

  - `config` (object)
    The baseline settings every stream inherits before any group or override applies.

  - `config.active` (boolean)
    Whether analysis runs, for every stream that does not say otherwise.

  - `config.listeners` (object)
    Listeners, keyed by name, applied to every stream that does not override them.

  - `config.processing` (object)
    Frame sampling and shipping settings applied to every stream that does not override them.

  - `config.processing.inference_fps` (integer)
    Frames per second sent to analysis; -1 matches the source rate. Default -1.

  - `config.processing.window_seconds` (number)
    Seconds per analysis window (scene/VLM/synthetic). Default 2.

  - `config.processing.video_height` (integer)
    Resize frames to this height; -1 matches source, 0 matches the model. Default 0.

  - `config.processing.grayscale` (boolean)
    Send frames in grayscale. Default false.

  - `config.processing.frame_source` (string)
    Capture frames via the transcoder or periodic frame grabs. Default transcoder, except the synthetic detector, which taps the source packets and defaults to grab.
    Enum: "transcoder", "grab"

  - `config.processing.grab_interval_seconds` (number)
    Frame-grab period when frame_source is grab. Default 1.

  - `config.processing.buffer_frames` (integer)
    Frames buffered awaiting processing. Sized from the incoming video by default.

  - `config.processing.auto_throttle` (boolean)
    Reduce inference_fps automatically when inference falls behind. Default off.

  - `config.processing.catch_up` (object,null)
    Scene/VLM — skip stale backlog to the live edge when inference lags.

  - `config.processing.catch_up.enabled` (boolean)
    Default true.

  - `config.processing.catch_up.max_behind_seconds` (number)
    Default is the buffer's own headroom.

  - `config.processing.rollup_interval_seconds` (number)
    How long detections are held for batch/rollup listener events. Default 2.

  - `config.processing.gpu_ids` (array,null)
    Pin VIS-side inference to these GPUs; null lets VIS balance.

  - `config.service` (object)
    Which Video Intelligence Service analyzes streams that do not override it.

  - `config.service.url` (string)
    VIS WebSocket endpoint, e.g. ws://vis-host:5001/ws/stream/.

  - `config.service.api_key` (string,null)
    Never echoed by a read. On a write: absent or null keeps the stored value, an empty string clears it.

  - `config.service.model_idle_timeout_seconds` (integer,null)
    How long VIS keeps an idle model loaded.

  - `config.diagnostics` (object)
    Debug aids applied to every stream that does not override them.

  - `config.diagnostics.save_images` (boolean)
    Save captured frames to disk on the Engine host. Default false.

  - `config.diagnostics.timing_log_seconds` (integer)
    Seconds between timing-metric dumps; 0 disables. Default 0.

  - `config.diagnostics.max_logged_messages` (integer)
    Protocol messages logged; -1 all, 0 disabled. Default 20.

  - `detectors` (object)
    Detector baselines for every type at once: a stream inherits the entry matching its own detector type. The default config selects no type, which is why these sit beside config rather than in it: config.detector selects one, and this document is the one that cannot.

  - `detectors.scene` (object,null)
    The analysis running on a stream. type selects the subtype; a patch that changes
it replaces the whole detector section.

  - `detectors.scene.type` (string, required)
    Detector subtype: scene, object, vlm, or synthetic.
    Enum: "scene", "object", "vlm", "synthetic"

  - `detectors.scene.classes` (array)
    Scene classes to detect.

  - `detectors.scene.sensitivity` (integer)
    Higher detects more; per-class overrides in class_sensitivity. Default 5.

  - `detectors.scene.class_sensitivity` (object)
    Per-class sensitivity overrides, keyed by class name; unlisted classes use sensitivity.

  - `detectors.scene.min_confidence` (number)
    Detections below this confidence are dropped. Default 0.3.

  - `detectors.scene.baseline` (object)
    The class set frame scores are normalized against.

  - `detectors.scene.baseline.set` (string,null)
    Named baseline: DEFAULT is ~1560 general scenes, TRAFFIC ~190 traffic scenes. Null falls back to custom_classes.
    Enum: "DEFAULT", "TRAFFIC"

  - `detectors.scene.baseline.custom_classes` (array,null)
    Baseline classes given outright, used when set is null. Enough of them to describe what the camera normally sees, or scores normalize against too little.

  - `detectors.object` (object,null)
    The analysis running on a stream. type selects the subtype; a patch that changes
it replaces the whole detector section.

  - `detectors.object.classes` (array,null)
    Classes to report; null reports all model classes.

  - `detectors.object.model` (string)
    Model variant. Ignored when checkpoint_path is set. Default medium.
    Enum: "nano", "small", "medium", "large"

  - `detectors.object.checkpoint_path` (string,null)
    Custom model weights on the VIS host; overrides model.

  - `detectors.object.tracking` (object,null)
    Absent or null inherits; {"method": "none"} turns tracking off.

  - `detectors.object.tracking.method` (string, required)
    byte-track assigns persistent IDs; none reports each frame's detections on their own. The remaining members apply to byte-track only.
    Enum: "byte-track", "none"

  - `detectors.object.tracking.min_confidence_to_create` (number)
    Confidence needed for a detection to start a new track.

  - `detectors.object.tracking.min_consecutive_frames` (integer)
    Frames an object must persist before its track becomes visible.

  - `detectors.object.tracking.min_overlap` (number)
    Overlap fraction for consecutive detections to match a track.

  - `detectors.object.tracking.max_lost_frames` (integer)
    Frames a track survives without detections.

  - `detectors.object.tracking.ignore_untracked` (boolean)
    Drop detections that have no track.

  - `detectors.object.tiling` (object,null)
    Absent or null inherits; {"mode": "none"} turns tiling off.

  - `detectors.object.tiling.mode` (string, required)
    none runs no tiling; fixed runs one grid per frame; gated runs probe + coarse + fine grids.
    Enum: "none", "fixed", "gated"

  - `detectors.object.tiling.min_grid` (object)
    Grid size and shape for the coarse/probe pass in gated mode.

  - `detectors.object.tiling.min_grid.rows` (integer, required)
    Number of tile rows.

  - `detectors.object.tiling.min_grid.cols` (integer, required)
    Number of tile columns.

  - `detectors.object.tiling.max_grid` (object)
    Grid size and shape for the full-resolution tiling pass. Required for every mode but none.

  - `detectors.object.tiling.tile_coverage_cutoff` (number)
    Drop tile detections covering more than this fraction of the tile; 1.0 disables.

  - `detectors.object.tiling.full_frame_pass` (boolean)
    fixed mode: also run a full-frame pass for objects larger than a tile.

  - `detectors.object.tiling.cluster_suppression_min_children` (integer)
    Drop a detection containing at least this many smaller ones; 0 disables.

  - `detectors.vlm` (object,null)
    The analysis running on a stream. type selects the subtype; a patch that changes
it replaces the whole detector section.

  - `detectors.vlm.endpoint` (object,null)
    Null inherits from the default config, and then the built-in http://vlm.docker:8000/v1 with Qwen/Qwen3-VL-4B-Instruct-FP8.

  - `detectors.vlm.endpoint.url` (string,null)
    OpenAI-compatible endpoint, e.g. http://vlm.docker:8000/v1.

  - `detectors.vlm.endpoint.model` (string,null)
    Model name to request from the endpoint.

  - `detectors.vlm.endpoint.timeout_seconds` (number)
    Request timeout, in seconds.

  - `detectors.vlm.endpoint.max_concurrent_requests` (integer)
    Maximum requests sent to the endpoint at once.

  - `detectors.vlm.mode` (string, required)
    Which analysis family runs. Only the matching block below applies.
    Enum: "detect", "describe", "custom"

  - `detectors.vlm.detect` (object,null)
    Settings for mode: detect; applies only when mode is detect.

  - `detectors.vlm.detect.classes` (array, required)
    Classes to look for.

  - `detectors.vlm.detect.class_hints` (object,null)
    Per-class hints inlined into the prompt; keys must be members of classes.

  - `detectors.vlm.detect.reasoning_level` (string,null)
    Built-in prompt preset VIS applies server-side: low and medium select its own prompt pairs plus a per-class boolean schema; high or absent uses the default class-aware prompts.
    Enum: "low", "medium", "high"

  - `detectors.vlm.custom` (object,null)
    Settings for mode: custom; applies only when mode is custom.

  - `detectors.vlm.custom.prompt` (object,null)
    Caller-authored prompt; null uses the endpoint's own default prompt.

  - `detectors.vlm.custom.prompt.system` (string,null)
    System prompt text.

  - `detectors.vlm.custom.prompt.user` (string,null)
    User prompt text.

  - `detectors.vlm.custom.response_schema` (object,null)
    JSON Schema forwarded verbatim to the endpoint.

  - `detectors.vlm.custom.classes` (array)
    Classes expanded into the {class_list} placeholder wherever either prompt uses it. Optional, and not a class list the analysis service filters on: in this mode the prompt decides what the model is asked, and these only render into it.

  - `detectors.vlm.custom.class_hints` (object,null)
    Per-class hints inlined into {class_list}; keys must be members of classes.

  - `detectors.vlm.generation` (object,null)
    Sampling parameters shared across every mode.

  - `detectors.vlm.generation.temperature` (number,null)
    Sampling temperature passed to the endpoint.

  - `detectors.vlm.generation.max_tokens` (integer,null)
    Maximum tokens the endpoint may generate.

  - `detectors.synthetic` (object,null)
    The analysis running on a stream. type selects the subtype; a patch that changes
it replaces the whole detector section.

  - `detectors.synthetic.endpoint` (object,null)
    Absent or null inherits from the default config.

  - `detectors.synthetic.endpoint.address` (string,null)
    gRPC host:port (not an http URL), e.g. svd.docker:8001.

  - `detectors.synthetic.endpoint.tls` (object,null)
    TLS settings for the connection; null auto-detects.

  - `detectors.synthetic.endpoint.tls.enabled` (boolean,null)
    Force TLS on or off; null auto-detects from the port and configured material.

  - `detectors.synthetic.endpoint.tls.ca_cert` (string,null)
    Path to the CA certificate on the VIS host, not the certificate itself (e.g. /certs/ca-cert.pem). Needed when the endpoint presents a private-CA certificate.

  - `detectors.synthetic.endpoint.tls.client_cert` (string,null)
    Path to the client certificate on the VIS host, for mutual TLS. Set it together with client_key; one without the other does not authenticate.

  - `detectors.synthetic.endpoint.tls.client_key` (string,null)
    Never echoed by a read. On a write: absent or null keeps the stored value, an empty string clears it.

  - `detectors.synthetic.endpoint.function_id` (string,null)
    NVIDIA Cloud Function ID, when the endpoint is served through NVCF.

  - `detectors.synthetic.classification_threshold` (number)
    Verdict is synthetic when the score exceeds this.

  - `etag` (string,null)
    This document's revision, to quote as If-Match on a write. Carried on the document; a read repeats it in the ETag header. Server-assigned and ignored on a write.

  - `concurrent_executions` (object)
    Parallel model instances per detector kind on VIS. The consumed kinds are object_detection and scene_detection; any other key is a 400 rather than silently dropped.

## Response 400 fields (application/problem+json):

  - `type` (string)
    URI identifying the problem type.

  - `title` (string, required)
    Short, human-readable summary of the problem type.

  - `status` (integer, required)
    The HTTP status code, repeated from the response line.

  - `detail` (string)
    Human-readable explanation specific to this occurrence.

  - `instance` (string)
    URI identifying this specific occurrence of the problem.

## Response 412 fields (application/problem+json):

  - `type` (string)
    URI identifying the problem type.

  - `title` (string, required)
    Short, human-readable summary of the problem type.

  - `status` (integer, required)
    The HTTP status code, repeated from the response line.

  - `detail` (string)
    Human-readable explanation specific to this occurrence.

  - `instance` (string)
    URI identifying this specific occurrence of the problem.

## Response 428 fields (application/problem+json):

  - `type` (string)
    URI identifying the problem type.

  - `title` (string, required)
    Short, human-readable summary of the problem type.

  - `status` (integer, required)
    The HTTP status code, repeated from the response line.

  - `detail` (string)
    Human-readable explanation specific to this occurrence.

  - `instance` (string)
    URI identifying this specific occurrence of the problem.

## Response default fields (application/problem+json):

  - `type` (string)
    URI identifying the problem type.

  - `title` (string, required)
    Short, human-readable summary of the problem type.

  - `status` (integer, required)
    The HTTP status code, repeated from the response line.

  - `detail` (string)
    Human-readable explanation specific to this occurrence.

  - `instance` (string)
    URI identifying this specific occurrence of the problem.