Skip to main content

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, auth, 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"}}
ParameterTypeDescription
keystringSet to storage
value.originals_rootstringS3 bucket name for original asset files
value.originals_root_folderstringPath prefix for objects in the bucket
value.derivatives_rootstringS3 bucket name for image conversions
value.derivatives_root_folderstringPath prefix for objects in the bucket
value.transcodes_rootstringS3 bucket name for video transcodes
value.transcodes_root_folderstringPath prefix for objects in the bucket

Auth​

Update authentication keys and authorized domains. All keys 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"}}
ParameterTypeDescription
keystringSet to auth
value.upload_keystringRFC4122-compliant UUID4 hex value (alphanumeric only, no dashes)
value.authorized_domainsstringComma-separated domain names (max 10). Empty allows all. Naked domains authorize subdomains.
value.dropbox_app_keystringDropbox App Key for File Picker uploads
value.dropbox_app_secretstringDropbox App Secret for File Picker uploads
value.api_keystringRFC4122-compliant UUID4 hex value (alphanumeric only, no dashes)

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}}}
ParameterTypeDescription
keystringSet to webhook
value.web_urlsstringComma-separated URLs (max 3). Can be empty.
value.callback_eventsJSONEvent 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 5 conversions (including deepzoom). deepzoom only accepts watermark, enabled, public.

Video​

Update video transcode, preview, and thumbnail settings. 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.

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