Update Settings

PATCH /api/v1/user/settings/update

Update account settings by sending a PATCH request with a partial settings payload. The JSON payload uses a key/value structure where key identifies the settings section to update.

Valid keys: storage, webhook, database, image, video, addons, watermark

Storage

Update S3 storage bucket configuration. All keys are mandatory.

warning

If using different S3 buckets for Originals, Derivatives and Transcodes, all buckets must be in the same region.

{
  "key": "storage",
  "value": {
    "originals_root": "MY-S3-BUCKET",
    "originals_root_folder": "folder/path",
    "derivatives_root": "MY-S3-BUCKET",
    "derivatives_root_folder": "folder/path",
    "transcodes_root": "MY-S3-BUCKET",
    "transcodes_root_folder": "folder/path"
  }
}

Parameter	Type	Description
`key`	string	Set to `storage`
`value`.`originals_root`	string	S3 bucket name for original asset files
`value`.`originals_root_folder`	string	Path prefix for objects in the bucket
`value`.`derivatives_root`	string	S3 bucket name for image conversions
`value`.`derivatives_root_folder`	string	Path prefix for objects in the bucket
`value`.`transcodes_root`	string	S3 bucket name for video transcodes
`value`.`transcodes_root_folder`	string	Path prefix for objects in the bucket

Webhook

Update webhook callback URLs and events. All keys mandatory.

{
  "key": "webhook",
  "value": {
    "web_urls": "https://myapp.example.org/receiver",
    "callback_events": {
      "file-saved": true,
      "file-processed": true,
      "file-data-updated": true,
      "file-deleted": true,
      "file-undeleted": true,
      "addon-processed": false
    }
  }
}

Parameter	Type	Description
`key`	string	Set to `webhook`
`value`.`web_urls`	string	Comma-separated URLs (max 3). Can be empty.
`value`.`callback_events`	JSON	Event flags: `file-saved`, `file-processed`, `file-data-updated`, `file-deleted`, `file-undeleted`, `addon-processed`

Database

Update external database export configuration. All keys mandatory.

{
  "key": "database",
  "value": {
    "db_url": "mysql://USER:PASSWORD@DB_HOST/DATABASE"
  }
}

All webhook events are auto-enabled for database export. Use empty db_url to disable.

Image

Update image conversion settings. Maximum 10 conversions (including deepzoom). The deepzoom conversion only accepts watermark, enabled, public.

{
  "key": "image",
  "value": {
    "on_demand_image_private": false,
    "conversions": [
      {
        "key": "500x500WEB",
        "value": {
          "format": "jpg",
          "watermark": false,
          "enabled": true,
          "public": false,
          "height": 500,
          "width": 500,
          "dpi": 72
        }
      },
      {
        "key": "deepzoom",
        "value": {
          "watermark": false,
          "enabled": false,
          "public": true
        }
      }
    ]
  }
}

Parameter	Type	Description
`key`	string	Set to `image`
`value`.`on_demand_image_private`	boolean	`true` to restrict on-demand image access to authenticated users
`value`.`conversions`	array	List of image conversion objects (max 10)
`conversions[].key`	string	Conversion name (min 3 characters), e.g. `500x500WEB`, `orig_web`, `deepzoom`
`conversions[].value.format`	string	Output format: `jpg`, `png`, `webp`
`conversions[].value.watermark`	boolean	Apply watermark to this conversion
`conversions[].value.enabled`	boolean	Enable this conversion for new uploads
`conversions[].value.public`	boolean/string	Public access for this conversion
`conversions[].value.height`	integer	Output height in pixels (omit or empty string for original size)
`conversions[].value.width`	integer	Output width in pixels (omit or empty string for original size)
`conversions[].value.dpi`	integer	Output DPI (e.g. `72`, `150`, `300`)

Video

Update video transcode, preview, and thumbnail settings. All four top-level keys are required.

Aspect options: pad, preserve, scale, crop. Storyboard modes: number, second, keyframes. Transcode keys: 360p-video, 360p-wm-video, 480p-video, 480p-wm-video, 720p-video, 720p-wm-video, 1080p-video, 1080p-wm-video, hls-video.

{
  "key": "video",
  "value": {
    "video_transcode_test_mode": false,
    "thumbnails": {
      "video_default": {
        "width": 480,
        "height": 360
      },
      "storyboard": {
        "enabled": true,
        "mode": "number",
        "mode_value": 10,
        "width": 320,
        "height": 240,
        "public": true,
        "aspect": "pad",
        "padding": "000000",
        "upscale": false
      }
    },
    "preview": {
      "video_preview_enabled": true,
      "video_preview_public": true,
      "video_preview_start": 0,
      "video_preview_length": 60,
      "video_preview_preset": "480p-wm-video",
      "video_preview_aspect": "pad",
      "video_preview_padding": "000000",
      "video_preview_upscale": false
    },
    "transcodes": {
      "480p-video": {
        "watermark": false,
        "enabled": true,
        "public": false,
        "aspect": "pad",
        "padding": "000000",
        "upscale": false
      },
      "720p-video": {
        "watermark": false,
        "enabled": false,
        "public": false,
        "aspect": "pad",
        "padding": "000000",
        "upscale": false
      },
      "hls-video": {
        "watermark": true,
        "enabled": false,
        "public": true,
        "aspect": "pad",
        "padding": "000000",
        "upscale": false
      }
    }
  }
}

Note: The transcodes object above shows a subset for brevity. All nine transcode keys must be included: 360p-video, 360p-wm-video, 480p-video, 480p-wm-video, 720p-video, 720p-wm-video, 1080p-video, 1080p-wm-video, hls-video.

Parameter	Type	Description
`key`	string	Set to `video`
`value`.`video_transcode_test_mode`	boolean	Enable test mode (transcodes are not triggered automatically)
`value`.`thumbnails.video_default`	object	Default video thumbnail size: `width` (10-1920), `height` (10-1080)
`value`.`thumbnails.storyboard`	object	(optional) Storyboard settings: `enabled`, `mode`, `mode_value`, `width`, `height`, `public`, `aspect`, `padding`, `upscale`
`value`.`preview`	object	Video preview clip settings
`preview.video_preview_enabled`	boolean	Enable preview clip generation
`preview.video_preview_public`	boolean	Public access for preview clips
`preview.video_preview_start`	integer	Start time in seconds
`preview.video_preview_length`	integer	Preview duration in seconds
`preview.video_preview_preset`	string	Transcode preset to use for preview (must be one of the transcode keys)
`preview.video_preview_aspect`	string	Aspect mode: `pad`, `preserve`, `scale`, `crop`
`preview.video_preview_padding`	string	Hex color for padding (e.g. `000000`)
`preview.video_preview_upscale`	boolean	Allow upscaling
`value`.`transcodes`	object	Transcode presets keyed by resolution name
`transcodes.{preset}`	object	Per-preset settings: `watermark`, `enabled`, `public`, `aspect`, `padding`, `upscale`

Addons

See Update Addons Settings for the dedicated endpoint.

Watermark

Update watermark placement and scaling. See Update Watermark for the two-step process (upload image, then confirm via this PATCH with key: "watermark").

Request

Responses

Successful operation

Update Settings

/api/v1/user/settings/update

Storage​

Webhook​

Database​

Image​

Video​

Addons​

Watermark​

Request​

Responses​