docs(API): Document upload file_format and async state contract #STRINGS-3096

doc/compiled.json

@@ -2099,7 +2099,8 @@
             "type": "string"
           },
           "state": {
-            "type": "string"
+            "type": "string",
+            "description": "Processing state of the upload: `initialized`, `processing`, `success`, or `error`. `error` means processing failed — for example the file could not be parsed, or a provided `file_format` didn't match the file's actual content. Poll this field until it leaves `initialized`/`processing` to get the final outcome.\n"
           },
           "error_message": {
             "type": "string",
@@ -16811,7 +16812,7 @@
     "/projects/{project_id}/uploads": {
       "post": {
         "summary": "Upload a new file",
-        "description": "Upload a new language file. Creates necessary resources in your project.\n\nNote: be aware of [upload limits](https://support.phrase.com/hc/en-us/articles/8548271212188-Phrase-Strings-Limits#file-size-upload-limits-0-0).\n",
+        "description": "Upload a new language file. Creates necessary resources in your project.\n\nThe upload is processed asynchronously: this endpoint returns `201 Created` once the file has been accepted and enqueued, not once processing has finished. Poll `GET /projects/{project_id}/uploads/{id}` and check the `state` field — `error` means processing failed (for example, an unparseable file or a `file_format` that doesn't match the file's actual content).\n\nNote: be aware of [upload limits](https://support.phrase.com/hc/en-us/articles/8548271212188-Phrase-Strings-Limits#file-size-upload-limits-0-0).\n",
         "operationId": "upload/create",
         "tags": [
           "Uploads"
@@ -16869,11 +16870,11 @@
         "x-code-samples": [
           {
             "lang": "Curl",
-            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/uploads\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X POST \\\n  -F branch=my-feature-branch \\\n  -F file=@/path/to/my/file.json \\\n  -F file_format=json \\\n  -F locale_id=abcd1234cdef1234abcd1234cdef1234 \\\n  -F tags=awesome-feature,needs-proofreading \\\n  -F locale_mapping[en]=2 \\\n  -F format_options[foo]=bar"
+            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/uploads\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X POST \\\n  -F branch=my-feature-branch \\\n  -F file=@/path/to/my/file.json \\\n  -F locale_id=abcd1234cdef1234abcd1234cdef1234 \\\n  -F tags=awesome-feature,needs-proofreading \\\n  -F locale_mapping[en]=2 \\\n  -F format_options[foo]=bar"
           },
           {
             "lang": "CLI v2",
-            "source": "phrase uploads create \\\n--project_id <project_id> \\\n--branch my-feature-branch \\\n--file /path/to/my/file.json \\\n--file_format json \\\n--locale_id abcd1234cdef1234abcd1234cdef1234 \\\n--tags awesome-feature,needs-proofreading \\\n--locale_mapping '{\"en\": \"2\"}' \\\n--format_options '{\"foo\": \"bar\"}' \\\n--access_token <token>"
+            "source": "phrase uploads create \\\n--project_id <project_id> \\\n--branch my-feature-branch \\\n--file /path/to/my/file.json \\\n--locale_id abcd1234cdef1234abcd1234cdef1234 \\\n--tags awesome-feature,needs-proofreading \\\n--locale_mapping '{\"en\": \"2\"}' \\\n--format_options '{\"foo\": \"bar\"}' \\\n--access_token <token>"
           }
         ],
         "requestBody": {
@@ -16901,7 +16902,7 @@
                     "example": "/path/to/my/file.json"
                   },
                   "file_format": {
-                    "description": "File format. Auto-detected when possible and not specified.",
+                    "description": "File format of the uploaded file, given as a format's `api_name`. See our [Formats API Endpoint](/en/api/strings/formats/list-formats) for the full list of supported formats.\n\nOptional. When omitted, Phrase tries to auto-detect the format from the file's content. This is not always possible for JSON files, since several JSON-based formats (e.g. `json`, `simple_json`, `nested_json`) share the same structure.\n",
                     "type": "string",
                     "example": "json"
                   },
@@ -17115,7 +17116,7 @@
     "/projects/{project_id}/uploads/{id}": {
       "get": {
         "summary": "Get a single upload",
-        "description": "View details and summary for a single upload.",
+        "description": "View details and summary for a single upload. Use this endpoint to poll for the outcome of an upload created via `POST /projects/{project_id}/uploads` — check the `state` field.\n",
         "operationId": "upload/show",
         "tags": [
           "Uploads"

paths/uploads/create.yaml

@@ -2,6 +2,8 @@ summary: Upload a new file
 description: |
   Upload a new language file. Creates necessary resources in your project.
 
+  The upload is processed asynchronously: this endpoint returns `201 Created` once the file has been accepted and enqueued, not once processing has finished. Poll `GET /projects/{project_id}/uploads/{id}` and check the `state` field — `error` means processing failed (for example, an unparseable file or a `file_format` that doesn't match the file's actual content).
+
   Note: be aware of [upload limits](https://support.phrase.com/hc/en-us/articles/8548271212188-Phrase-Strings-Limits#file-size-upload-limits-0-0).
 operationId: upload/create
 tags:
@@ -44,7 +46,6 @@ x-code-samples:
         -X POST \
         -F branch=my-feature-branch \
         -F file=@/path/to/my/file.json \
-        -F file_format=json \
         -F locale_id=abcd1234cdef1234abcd1234cdef1234 \
         -F tags=awesome-feature,needs-proofreading \
         -F locale_mapping[en]=2 \
@@ -55,7 +56,6 @@ x-code-samples:
       --project_id <project_id> \
       --branch my-feature-branch \
       --file /path/to/my/file.json \
-      --file_format json \
       --locale_id abcd1234cdef1234abcd1234cdef1234 \
       --tags awesome-feature,needs-proofreading \
       --locale_mapping '{"en": "2"}' \
@@ -83,7 +83,10 @@ requestBody:
             format: binary
             example: "/path/to/my/file.json"
           file_format:
-            description: File format. Auto-detected when possible and not specified.
+            description: |
+              File format of the uploaded file, given as a format's `api_name`. See our [Formats API Endpoint](/en/api/strings/formats/list-formats) for the full list of supported formats.
+
+              Optional. When omitted, Phrase tries to auto-detect the format from the file's content. This is not always possible for JSON files, since several JSON-based formats (e.g. `json`, `simple_json`, `nested_json`) share the same structure.
             type: string
             example: json
           locale_id:

paths/uploads/show.yaml

@@ -1,6 +1,7 @@
 ---
 summary: Get a single upload
-description: View details and summary for a single upload.
+description: |
+  View details and summary for a single upload. Use this endpoint to poll for the outcome of an upload created via `POST /projects/{project_id}/uploads` — check the `state` field.
 operationId: upload/show
 tags:
 - Uploads

schemas/upload.yaml

@@ -11,6 +11,8 @@ upload:
       type: string
     state:
       type: string
+      description: |
+        Processing state of the upload: `initialized`, `processing`, `success`, or `error`. `error` means processing failed — for example the file could not be parsed, or a provided `file_format` didn't match the file's actual content. Poll this field until it leaves `initialized`/`processing` to get the final outcome.
     error_message:
       type: string
       nullable: true