Skip to content

Update available browse layouts

PATCH
/admin/system/browse-views

Replaces the set of enabled browse layouts.

You need system.config.write or system.admin for the whole install; read permission isn’t enough, and a permission held only for a team doesn’t count. A body that can’t be decoded gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.

Send at least one of grid, masonry, thumbnail, list or feed. Names are case-sensitive and aren’t trimmed. One name is enough, duplicates are removed, and the response lists the chosen layouts in that order.

An empty, missing or null enabled list, a JSON null body, or any unknown name gets a 400 and saves nothing. Malformed JSON or a wrong field type also gets a 400. A database error on save is reported as a 400 too, and that error doesn’t mean the previous value is still in place.

After saving, the server clears this app instance’s cached layout list and tries to notify the other instances; a failed notification doesn’t fail the save. Other instances can keep the old list, and a read already in progress can put old data back into a cache. So a successful response doesn’t guarantee that every client’s next request sees the new set.

The web client checks the layout saved on the device, the account default and the device-based fallback against the enabled set, and uses the first enabled layout if none of them is available. The browser that saved the change applies it at once, but other open browsers aren’t told. Turning a layout off doesn’t restrict access to content.

Auditing is attempted after the save and isn’t guaranteed. There’s no version check, so concurrent updates can overwrite each other, and the response shows this request’s resolved set rather than a fresh read.

The browse layouts this instance offers. They control how content is shown, not who can read it.

object
enabled
required

Enabled layout names, returned in the order grid, masonry, thumbnail, list, feed. A write needs at least one recognized name, and any unknown name rejects the whole write. Names are case-sensitive and aren’t trimmed; duplicates are accepted and removed. On reads, a missing or empty saved list means all five; unknown saved names are skipped, and if none is left you get all five.

Array<string>
>= 1 items
Allowed values: grid masonry thumbnail list feed
Example
[
"grid",
"list",
"feed"
]

The enabled layouts this request saved, with duplicates removed, in their standard order.

The browse layouts this instance offers. They control how content is shown, not who can read it.

object
enabled
required

Enabled layout names, returned in the order grid, masonry, thumbnail, list, feed. A write needs at least one recognized name, and any unknown name rejects the whole write. Names are case-sensitive and aren’t trimmed; duplicates are accepted and removed. On reads, a missing or empty saved list means all five; unknown saved names are skipped, and if none is left you get all five.

Array<string>
>= 1 items
Allowed values: grid masonry thumbnail list feed
Example
[
"grid",
"list",
"feed"
]

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed