Description

The API documentation for the "Upload file" endpoint (POST /api/v2/files) states that it returns 201 Created, but the actual implementation can return either:

• 200 OK - when the file already exists (same hash and creator)
• 201 Created - when a new file is uploaded

Current Documentation

The Swagger annotation in coderd/files.go only documents the 201 response:

// @Success 201 {object} codersdk.UploadResponse

Actual Behavior

From coderd/files.go:

file, err := api.Database.GetFileByHashAndCreator(ctx, database.GetFileByHashAndCreatorParams{
    Hash:      hash,
    CreatedBy: apiKey.UserID,
})
if err == nil {
    // The file already exists!
    httpapi.Write(ctx, rw, http.StatusOK, codersdk.UploadResponse{
        ID: file.ID,
    })
    return
}
// ... later ...
httpapi.Write(ctx, rw, http.StatusCreated, codersdk.UploadResponse{
    ID: file.ID,
})

Suggested Fix

Update the Swagger annotations to document both response codes:

// @Success 200 {object} codersdk.UploadResponse "File already exists"
// @Success 201 {object} codersdk.UploadResponse "File created"

Reproduction

A user reported this discrepancy when uploading a tar file:

curl --data @out.tar --header "Coder-Session-Token: <token>" https://<instance>/api/v2/files --header "content-type: application/x-tar" -v

Returned HTTP/1.1 200 OK instead of the documented 201 Created (because the file already existed).