docs: document asset download endpoint (GET /api/assets/{id}/content)

openapi-cloud.yaml

@@ -1425,6 +1425,75 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+  /api/assets/{id}/content:
+    get:
+      tags:
+        - asset
+      summary: Download asset content
+      description: |
+        Downloads the binary content of an asset.
+
+        By default, the response is served with `Content-Disposition: attachment`, prompting
+        the client to save the file. Pass `disposition=inline` to serve the content inline
+        (useful for displaying images directly in a browser).
+
+        The response `Content-Type` matches the asset's stored MIME type, and a `3xx` redirect
+        may be returned to a pre-signed storage URL — follow redirects (`curl -L`) when consuming.
+      operationId: getAssetContent
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Asset ID
+          schema:
+            type: string
+            format: uuid
+        - name: disposition
+          in: query
+          required: false
+          description: |
+            Content-Disposition for the response. `attachment` (default) prompts a download;
+            `inline` serves the content for direct display.
+          schema:
+            type: string
+            enum:
+              - attachment
+              - inline
+            default: attachment
+      responses:
+        '200':
+          description: Asset content
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '302':
+          description: Redirect to a pre-signed storage URL containing the asset content
+          headers:
+            Location:
+              description: Pre-signed URL where the asset content can be downloaded
+              schema:
+                type: string
+                format: uri
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Asset not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
   /api/assets/{id}/tags:
     post:
       tags: