Uploads: replace a file in place, and say which file each version is

[jeremy]

Documents a new endpoint for replacing an upload's file, and corrects the
existing versions documentation.

New: Create an upload version

POST /uploads/2/versions.json replaces the file of an existing upload. The
upload keeps its ID, its URL and its comments, and the previous file stays
available as a past version.

Until now the only way to publish a new file was POST /vaults/2/uploads.json,
which creates a new upload with a new ID and a new URL. If you're shipping
successive releases of the same artifact, that means a folder filling up with
app-v0.8.1.exe, app-v0.8.2.exe, … and a download link that has to change
every time. Use the new endpoint when you want the link to keep working.

Takes the same attachable_sgid as Create an
attachment, plus optional
base_name and description. description is presence-aware: omit it to carry
the previous version's description forward, or send null to clear it. Returns
201 Created with the upload's JSON representation.

The project-scoped POST /buckets/1/uploads/2/versions.json also works and is
listed under the legacy routes.

Corrected: Get upload versions

The previous text said "Each version event represents a file replacement."
That was wrong — as the example response directly beneath it showed, with
"action": "created".

Three actions appear: created and active mark the upload's publication, and
blob_changed marks a file replacement. Filter on blob_changed to list only
replacements.

New: the upload object on version events

Version events previously carried event metadata only, so you could tell that
something changed but not which file. Each version event now includes an
upload object:

• filename, content_type and byte_size — the file as it was at that
  version.
• download_url — that specific version's file. The upload's own download_url
  always serves the latest.
• app_download_url — the equivalent link for the Basecamp web app.
• current — true for the most recent version, false for the rest.

One nuance worth reading before you rely on current: it means the newest
version, which isn't necessarily the file you get from the upload's own
download_url. Updating an upload changes its metadata without recording a new
version, so the two can differ. The documentation says this explicitly.

This is an additive change. Existing fields are unchanged.

---

Synced from bc3 doc/api/ by script/api/sync_to_bc3_api — not a hand-edit.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[jeremy]

Updated: both create endpoints now document the 507 Insufficient Storage returned when an account has reached its storage limit. Replacing a file stores the new version alongside every past one, so it counts against storage — and creating an upload could already return this, it just wasn't written down.

Synced from bc3 doc/api/ by script/api/sync_to_bc3_api — not a hand-edit.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[jeremy]

Updated: documents that the upload object is omitted — not null — on a version whose file has since been removed from the account. The version event itself is still listed, so decode upload as optional.

Synced from bc3 doc/api/ by script/api/sync_to_bc3_api — not a hand-edit.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.