Skip to content

API: allow editing and deleting a published version (at least files[].externalUrl) #1603

Open

Description

@EndlessPixel

Is your feature request related to a problem?

The v1 API can create a version but can never change or remove one afterwards. For an "external URL" version (files[].externalUrl) that means a wrong URL — a typo, or the file host renaming its assets — can only be repaired by deleting the version in the web UI and re-creating it through the API.

$ curl -X OPTIONS -i https://hangar.papermc.io/api/v1/projects/{slug}/versions/{name}
allow: GET,HEAD,OPTIONS          # no PATCH, no DELETE

$ curl -X PATCH  .../versions/{name}   -> 405
$ curl -X DELETE .../versions/{name}   -> 405

/v3/api-docs only exposes GET, POST /upload (create) and /stats for version paths. Editing and deleting exist only under /api/internal/versions/version/{projectId}/{versionId}/... (including a soft delete and a hardDelete), which can't be driven by an API key.

Real-world case: I maintain FakePlayer-CE, a Paper plugin. A batch of versions was published pointing at

.../releases/download/fp.build16/fakeplayer-fp.fp.build16.jar   -> 404
.../releases/download/fp.build16/fakeplayer-fp.build16.jar      -> 200

Every download link on the project page 404'd. Nothing surfaced it: external downloads aren't tracked (stats stay at 0, which reads as "nobody uses this"), and GET /versions/{name}/PAPER/download is a 404 for external files too (see #1122), so a scripted check against the API also reports "fine".

The only repair was to delete and re-create 14 versions. Both halves had to be done by hand: deletion because there is no DELETE, re-creation 14 times because the upload endpoint creates one version per call. And re-creating has a side effect users see — versions are listed by creation time (by design, see #1196), so the re-created old versions landed above the genuinely recent ones, and the download button follows the most recently created version. After an otherwise harmless metadata fix the public list read:

build9, build8, build7, ... build3, build16, build14, ...

Describe the solution you'd like

Four things, in order of how much they would have helped:

  1. PATCH /api/v1/projects/{slug}/versions/{name} — accept at least files[].externalUrl, ideally also description, platformDependencies and pluginDependencies. Even external-URL-only would remove the delete/re-create cycle entirely.

  2. DELETE /api/v1/projects/{slug}/versions/{name} — parity with what the web UI already lets a project member do, so bulk cleanup is scriptable. Reusing the existing soft-delete semantics (restorable, like the internal delete rather than hardDelete) would be enough; no new capability, just no longer requiring a browser. Right now removing 14 bad versions meant 14 clicks.

  3. Validate the external URL on create (and on edit) — HEAD it, reject or warn on non-2xx. Hangar would then have refused fourteen dead links instead of silently publishing them, and none of the above would have been necessary.

  4. Document that GET /api/v1/projects/{slug}/versions?limit=N caps N at 25 and silently clamps larger values (the response's pagination.limit says 25). My first query used limit=100 and returned 5 entries, which looked like "all the versions there are".

Describe alternatives you've considered

  • Delete + re-create through the web UI. What I ended up doing. Loses createdAt ordering and download stats, and isn't scriptable at either end.
  • Add a second file named like the typo. I uploaded duplicate assets so the broken URLs would resolve. Works, but doubles storage per release, only helps when you control the file host, and then has to be cleaned up again later.
  • Talking to /api/internal/.... Not usable with an API key, and I'd rather not have CI depend on an internal route.
  • Reordering / pinning. Deliberately not asking for it — I read Ability to sort versions and selection for the main download-button #1196 and kennytv's reasoning about non-chronological creation. The point is not needing a re-create in the first place.

Other

Happy to write the PATCH / DELETE handlers if you can point at where version mutations belong (whether v1 should reuse the internal save/delete logic or get proper routes). Reproducing both 405s is one curl each against any project with an existing version.

Activity

  1. changed the title [-]API: let a published version be edited (at least files[].externalUrl) instead of forcing delete + re-create[/-] [+]API: allow editing and deleting a published version (at least files[].externalUrl)[/+] on Nov 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions