From 50d42ab0b93a7b52cb54bffba63309bdca4acfe6 Mon Sep 17 00:00:00 2001
From: "blinkagent[bot]" <237617714+blinkagent[bot]@users.noreply.github.com>
Date: Mon, 8 Dec 2025 16:04:56 -0600
Subject: [PATCH] docs: document 200 OK response for upload file API when file
 exists (#21071)

Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
---
 coderd/apidoc/docs.go       | 8 +++++++-
 coderd/apidoc/swagger.json  | 8 +++++++-
 coderd/files.go             | 3 ++-
 docs/reference/api/files.md | 9 +++++----
 4 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
index a72269bb5e..d559851452 100644
--- a/coderd/apidoc/docs.go
+++ b/coderd/apidoc/docs.go
@@ -1290,8 +1290,14 @@ const docTemplate = `{
                     }
                 ],
                 "responses": {
+                    "200": {
+                        "description": "Returns existing file if duplicate",
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.UploadResponse"
+                        }
+                    },
                     "201": {
-                        "description": "Created",
+                        "description": "Returns newly created file",
                         "schema": {
                             "$ref": "#/definitions/codersdk.UploadResponse"
                         }
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
index cd60b4bf9c..d7282711a7 100644
--- a/coderd/apidoc/swagger.json
+++ b/coderd/apidoc/swagger.json
@@ -1116,8 +1116,14 @@
 					}
 				],
 				"responses": {
+					"200": {
+						"description": "Returns existing file if duplicate",
+						"schema": {
+							"$ref": "#/definitions/codersdk.UploadResponse"
+						}
+					},
 					"201": {
-						"description": "Created",
+						"description": "Returns newly created file",
 						"schema": {
 							"$ref": "#/definitions/codersdk.UploadResponse"
 						}
diff --git a/coderd/files.go b/coderd/files.go
index eaab00c401..c54cd50a75 100644
--- a/coderd/files.go
+++ b/coderd/files.go
@@ -41,7 +41,8 @@ const (
 // @Tags Files
 // @Param Content-Type header string true "Content-Type must be `application/x-tar` or `application/zip`" default(application/x-tar)
 // @Param file formData file true "File to be uploaded. If using tar format, file must conform to ustar (pax may cause problems)."
-// @Success 201 {object} codersdk.UploadResponse
+// @Success 200 {object} codersdk.UploadResponse "Returns existing file if duplicate"
+// @Success 201 {object} codersdk.UploadResponse "Returns newly created file"
 // @Router /files [post]
 func (api *API) postFile(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
diff --git a/docs/reference/api/files.md b/docs/reference/api/files.md
index 7b937876bb..ac8dc12e7e 100644
--- a/docs/reference/api/files.md
+++ b/docs/reference/api/files.md
@@ -31,7 +31,7 @@ file: string
 
 ### Example responses
 
-> 201 Response
+> 200 Response
 
 ```json
 {
@@ -41,9 +41,10 @@ file: string
 
 ### Responses
 
-| Status | Meaning                                                      | Description | Schema                                                       |
-|--------|--------------------------------------------------------------|-------------|--------------------------------------------------------------|
-| 201    | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created     | [codersdk.UploadResponse](schemas.md#codersdkuploadresponse) |
+| Status | Meaning                                                      | Description                        | Schema                                                       |
+|--------|--------------------------------------------------------------|------------------------------------|--------------------------------------------------------------|
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)      | Returns existing file if duplicate | [codersdk.UploadResponse](schemas.md#codersdkuploadresponse) |
+| 201    | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Returns newly created file         | [codersdk.UploadResponse](schemas.md#codersdkuploadresponse) |
 
 To perform this operation, you must be authenticated. [Learn more](authentication.md).