[API Request] Add readonly and maxAge to the playlist object returned by getPlaylist

[deluan]

Type of change

API tweak

Proposal description

Summary

This proposal adds two optional attributes to the existing playlist object returned by getPlaylist (and therefore to the playlist schema used across responses such as playlist and playlistWithSongs).

• readonly (boolean): signals that a playlist is not intended to be modified by clients.
• maxAge (integer seconds): signals how long the playlist contents can be treated as fresh (cache lifetime), inspired by HTTP Cache-Control: max-age.

These fields are additive and backward compatible.

Motivation

Some servers want to expose playlists whose contents are generated or maintained by the server itself, not edited by the user. Examples include:

• Smart Playlists generated server side (rule based): for example “Most played this month”, “Unplayed favorites”, “Recently added but not listened”, “Top rated in genre X”, “Played in the last N days”.
• Recommendation playlists: mixes driven by a recommender system, external services, or metadata agents.
• Periodic playlists: for example weekly discovery, daily mix, seasonal rotation.
• Large or expensive playlists: server computed lists with hundreds or thousands of tracks.

Two practical problems show up for clients today:

1. Editability ambiguity

Clients cannot reliably determine whether a playlist is intended to be user editable. Many clients will show edit actions by default, and the user discovers the playlist is not meant to be changed only after failures or surprising behavior.

2. No refresh guidance

For generated playlists, clients have no standard hint for refresh cadence. That leads to overfetching (wasted server work and bandwidth) or underfetching (stale results). This is especially painful for large playlists and offline first clients.

Proposed additions

1) readonly

• Type: boolean
• Required: no
• Default if omitted: false
• Meaning: The playlist is not intended to be modified by clients.

Client guidance

• When readonly=true, clients should hide or disable UI actions that modify the playlist, including renaming, reordering, adding tracks, removing tracks, or clearing the playlist.
• Clients may still allow non mutating actions such as play, queue, download, or view details.

Server guidance

• Servers should set readonly=true for playlists whose contents are owned by server logic (smart playlists, recommendation mixes, periodic playlists, curated system lists).

2) maxAge

• Type: integer
• Units: seconds
• Required: no
• Default if omitted: unspecified (clients keep current behavior)
• Meaning: A freshness lifetime for the playlist contents returned by getPlaylist. Clients may cache the playlist result and avoid refetching until the cached copy is older than maxAge seconds.

This is intentionally a relative lifetime (seconds) instead of an absolute timestamp. That keeps it aligned with HTTP caching semantics and avoids clock skew issues.

Client guidance

• If maxAge is present and maxAge > 0, clients may treat the playlist contents as fresh for maxAge seconds starting from the time the response was received.
• If maxAge == 0, clients should treat the response as immediately stale (effectively no caching).
• If omitted, clients should keep existing behavior.

Server guidance

• Servers should only set maxAge when they can reasonably expect the playlist contents to remain stable for that period.
• For server generated playlists, maxAge is especially useful when the server intentionally refreshes the generated contents on a cadence (for example daily or weekly), or when generation is expensive and results are cached.

Backward compatibility impact

• Additive fields only. Existing clients that ignore unknown fields continue to work.
• No endpoint or parameter changes are required for this proposal.
• The intent is purely to improve client UX and reduce unnecessary refetching.

Backward compatibility

• No backward compatibility impact.

API details

{
  "id": "800000075",
  "name": "Weekly Exploration",
  "owner": "johndoe",
  "public": true,
  "created": "2026-01-24T03:18:41+00:00",
  "changed": "2026-01-24T03:18:41+00:00",
  "songCount": 50,
  "duration": 14523,
  "readonly": true,
  "maxAge": 86400,
  "entry": [
    { "id": "300000060", "title": "BrownSmoke" }
  ]
}

Security impacts

None

Potential issues

No response

Alternative solutions

No response

[Tolriq]

Love this, but not sure about the max age this is a little different from caching for a few of the cases you expose.

A maxAge of 1 day, and query the playlist 1 second before the playlist is updated is not that useful.

What about validUntil with a timestamp as the changed ? Clients already parse those and the changed field to decide if they sync or not, so it's in line with current API. This would cover the need for all auto generated playlists with fixed runs.

And a minRefreshTime, that clearly indicate that clients should not refresh before that duration, unlike maxAge that sounds more like a suggestion.

[epoupon]

At first glance, I would have gone with a "datetime" stored in a expires field (like for Share).

[deluan]

I'm ok with datetime, but expires sounds a bit like the playlist will be gone after that point in time, when it's only the content that will change.

[epoupon]

Given the whole current specs, some random AI suggest validUntil. What do you think?

[deluan]

That was Tolriq's suggestion :)

If we prefer a datetime, I'm good with it.

[epoupon]

Ah yes, I am good with validUntil too then :)

[dweymouth]

Would readonly be a property of the playlist, or relative to the current authenticated user? From the client perspective, I think it should be the latter. For example, a playlist that is owned by user A but shared with users B and C, and only the owning user is allowed to edit, it should show up as readonly to users B and C. AFAIK, currently no server allows any user to edit tracks on a playlist they do not own, but in the future, some server may allow a playlist which is owned by A, to be edited by A and B, and played only by C, and the readonly property is a good way for C's client to know they're not allowed to edit it.

[dweymouth]

Could we change this line:

Meaning: The playlist is not intended to be modified by clients.

to

Meaning: The playlist is not intended to be modified by the current authenticated user.

[epoupon]

For the record, LMS imports m3u/m3u8 playlists. These playlists are public and read-only.
They are exposed through the Subsonic API with no owner (owner is an optional field). Since we usually consider only owners are allowed to modify playlists, this effectively works in mosts clients (though it has some caveats, as already mentioned).

That being said, I’m not sure the example with the ‘system’ owner fully applies. Smart playlists could still belong to users who enabled them or who have the relevant external service access via personal API keys, etc

[epoupon]

Specifically for permissions, there is already the allowedUser attribute for that, even though it is not used by any server AFAIK (even the OG Subsonic does not handle it properly)

Wow didn't even notice that field... Then why not considering an empty allowedUser sequence as read-only?

[deluan]

Wow didn't even notice that field...

Yeah, me neither! Crazy right?

Then why not considering an empty allowedUser sequence as read-only?

As this is (AFAICT) an incomplete feature in OG Subsonic (and Airsonic, Madsonic and AA), we would need to be sure the existing semantics are compatible with what you are suggesting. If they are, we can simply document it. If not, we should deprecate this.

[Tolriq]

With apikeys clients don't know current user name. Explicit read-only is nicer.

With that said if there's need to be even more explicit we can use an enum for the different cases. But not sure it's worth it.

[lachlan-00]

So readonly=true is basically an easy shorthand for clients to say that you can not use updatePlaylist function with this list?

If there is support for adding/removing songs to the playlist but not editing name is that still read only? (If it was just a simple all or nothing I'm fine with that.)

For maxAge you could just show the current time instead of 0 so there's always a time?

I like this idea as there are smart lists i have that take forever to load but rarely change content so being able to skip them in the client would be a great add.

[deluan]

Originally I thought about it being all or nothing, to keep things simple, but I'm open to suggestions.

For maxAge you could just show the current time instead of 0 so there's always a time?

I don't see the benefit. It's optional, if not there, no expiration. I see it would make things slightly easier for clients, but as we can't make this field mandatory (for backward compatibility), I don't see the point.

[lachlan-00]

No i think all or nothing is fine.

so missing / 0 / time() is all the same really then so that doesn't need changing as well