Update Settings

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

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

---

Storage

Update S3 storage bucket configuration. All keys are mandatory.

warning

If you are 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

---

Auth

Update authentication keys and authorized domains. All keys are mandatory (use empty strings to clear).

{
  "key": "auth",
  "value": {
    "upload_key": "UPLOAD_KEY",
    "authorized_domains": "filespin.io, myapp.example.org",
    "dropbox_app_key": "DROPBOX_KEY",
    "dropbox_app_secret": "DROPBOX_SECRET",
    "api_key": "API_KEY"
  }
}

Parameter	Type	Description
key	string	Set to auth
value.upload_key	string	RFC4122-compliant UUID4 hex value (alphanumeric only, no dashes)
value.authorized_domains	string	Comma-separated domain names allowed for this upload key. Empty allows all domains. Max 10 domains. Naked domains authorize all subdomains.
value.dropbox_app_key	string	Dropbox App Key for File Picker uploads
value.dropbox_app_secret	string	Dropbox App Secret for File Picker uploads
value.api_key	string	RFC4122-compliant UUID4 hex value (alphanumeric only, no dashes)

---

Webhook

Update webhook callback URLs and events. All keys are 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 (see table below)

Callback Events

Event	Description
file-saved	File stored in storage after upload
file-processed	Image/video conversions completed
file-data-updated	Custom data attached to a file
file-deleted	File or conversions deleted
file-undeleted	File restored via Undelete API
addon-processed	Addon processing completed

---

Database

Update external database export configuration. All keys are mandatory.

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

All webhook events are auto-enabled for database export.

Parameter	Type	Description
key	string	Set to database
value.db_url	string	MySQL connection URL. Can be empty to disable.

---

Image

Update image conversion settings. All keys are mandatory.

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

• deepzoom is a special key — only watermark, enabled, and public can be updated
• Maximum 5 conversions can be added/updated (including deepzoom)

Parameter	Type	Description
key	string	Set to image
value.is_on_demand_private	boolean	Whether on-demand images require signed URLs
value.conversions	JSON	List of conversion objects (max 5)
value.conversions.key	string	Unique name up to 20 alphanumeric characters (no spaces)
value.conversions.value.format	string	jpg or png
value.conversions.value.watermark	boolean	Apply account watermark to this conversion
value.conversions.value.enabled	boolean	Auto-generate on upload
value.conversions.value.public	boolean	Publicly accessible without signed URL
value.conversions.value.width	integer	Max width in pixels (original used if larger or empty)
value.conversions.value.height	integer	Max height in pixels (original used if larger or empty)

---

Video

Update video transcode, preview, and thumbnail settings. All keys are mandatory except storyboard (only needed when the Storyboard addon is enabled).

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

Aspect Options

Value	Description
pad	Add padding to fill requested dimensions
preserve	Preserve original aspect ratio (padding ignored)
scale	Scale output to match requested dimensions
crop	Crop output to match requested dimensions

Storyboard Modes

Mode	Description
number	Extract mode_value images evenly spaced over the video
second	Extract one image every mode_value seconds
keyframes	Extract keyframes (mode_value ignored)

Transcode Keys

Allowed keys: 360p-video, 360p-wm-video, 480p-video, 480p-wm-video, 720p-video, 720p-wm-video, 1080p-video, 1080p-wm-video, hls-video

Each transcode accepts: enabled, public, aspect, padding, upscale. The hls-video key additionally accepts watermark.

Preview Parameters

Parameter	Type	Description
video_preview_start	integer or timecode	Start time as seconds (e.g. 5) or timecode (%H:%M:%S.%f)
video_preview_length	integer	Clip length in seconds (defaults to entire video)
video_preview_preset	string	Any standard transcode key
video_preview_enabled	boolean	Enable video preview generation
video_preview_public	boolean	Make preview publicly accessible
video_preview_aspect	string	pad, preserve, scale, or crop
video_preview_padding	string	Hex color code without # (e.g. 000000)
video_preview_upscale	boolean	Upscale if source is smaller than requested size

---

Addons

Update addon settings. See Update Addons Settings for the dedicated endpoint.

---

Watermark

Update watermark image, placement, and scaling. See Upload Watermark for the two-step process.