Skip to content
calternal docs

Set Files preferences

PUT
/api/v1/files/preferences
curl --request PUT \
  --url https://example.com/api/v1/files/preferences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "show_dot_files": true, "show_sidecar_files": true }'

Requires a signed-in User with the data scope. It returns 400 for invalid input, 403 when access is denied, 409 when saved settings conflict, 413 when the request is too large, or 507 when the change cannot be stored. Route: /api/v1/files/preferences. Inputs: . Do not automatically replay this operation after an uncertain result.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Replace the two Files visibility preferences.

object
show_dot_files
required

Show names that start with U+002E in the User’s Home.

boolean
show_sidecar_files
required

Show paired XMP and Apple AAE sidecar files as separate entries.

boolean
Examplegenerated
{
  "show_dot_files": true,
  "show_sidecar_files": true
}

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

Visibility preferences for ordinary Files listings.

object
show_dot_files
required

Show names that start with U+002E in the User’s Home.

boolean
show_sidecar_files
required

Show paired XMP and Apple AAE sidecar files as separate entries.

boolean
Examplegenerated
{
  "show_dot_files": true,
  "show_sidecar_files": true
}

400

Section titled “400”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

403

Section titled “403”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

409

Section titled “409”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

413

Section titled “413”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

507

Section titled “507”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}