Update storage settings

Replaces the account-level storage lifecycle settings applied to newly uploaded fal CDN files. Omitted or null fields are cleared (reset to the system default), so always send the full desired configuration. Sending an empty JSON object {} clears all settings. To change a single setting, first GET the current settings and PUT the full object back with only that field changed.

A request whose body is not valid JSON (including a zero-length body) or whose Content-Type is not application/json is rejected with a 400 validation_error and the stored settings are unchanged.

ACL rules referencing users that do not exist are dropped. The response reflects the settings actually saved, so verify it contains the rules you sent.

These are the same settings that the per-request X-Fal-Object-Lifecycle-Preference header overrides on individual requests.

Authentication: Required. The API key must have the account:settings:write permission.

Required permissions: account:settings:write. Key presets that include them: FULL. See key permissions.

PUT

storage

settings

Update storage settings

curl --request PUT \
  --url https://api.fal.ai/v1/storage/settings \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.fal.ai/v1/storage/settings"

payload = {}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.fal.ai/v1/storage/settings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "expiration_duration_seconds": 86400,
  "initial_acl": {
    "default": "forbid",
    "rules": [
      {
        "user": "my-teammate",
        "decision": "allow"
      }
    ]
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

Key on the FULL preset, or any key whose permissions include the ones this API lists. Prefix it with "Key ", e.g. Authorization: Key YOUR_API_KEY

Body

application/json

Account-level storage lifecycle settings

expiration_duration_seconds

integer | null

Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration.

Required range: x >= 1

Example:

86400

initial_acl

object | null

Default ACL applied to newly uploaded files. Null uses the system default (public).

Show child attributes

Response

Storage settings after the update

Account-level storage lifecycle settings

expiration_duration_seconds

integer | null

required

Seconds after which newly uploaded files automatically expire, or null if auto-expiration is disabled

Example:

86400

initial_acl

object | null

required

Default ACL applied to newly uploaded files, or null if the system default (public) is used

Show child attributes

⌘I

Update storage settings

curl --request PUT \
  --url https://api.fal.ai/v1/storage/settings \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.fal.ai/v1/storage/settings"

payload = {}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.fal.ai/v1/storage/settings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "expiration_duration_seconds": 86400,
  "initial_acl": {
    "default": "forbid",
    "rules": [
      {
        "user": "my-teammate",
        "decision": "allow"
      }
    ]
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}