Set a file public or private

An idempotent SET, not a toggle. public is REQUIRED and must be a real JSON boolean: a missing key, the string "yes", the integer 1 and null are all 400s. An idempotent set has no defensible default, and guessing one is how a caller publishes a file it did not mean to publish.

Repeating the call is safe: changed reports whether this call was an actual transition, and side effects (the social preview image, the made_public_at stamp) run only on a real transition.

Setting a file public publishes it at a permanent, unauthenticated URL - see GET /v1/files/{uuid}/share.

Setting a file private is NOT an access control, and must not be described as one. It removes the public file page. It does NOT revoke access to the bytes: the legacy GET /api/files/serve/{uuid} and GET /api/files/thumbnail/{uuid}?original=true routes serve the same bytes to a caller with NO credentials at all, by deliberate design - those routes exist so browser <img> tags can load without credentials, and they treat the uuid itself as the capability. Anyone who kept the uuid keeps the bytes. Nothing already fetched or cached is retroactively unpublished either. Treat a file uuid you have ever made public as public forever.