openapi: 3.1.0 info: title: 'files API documentation' description: 'Website-scoped file storage and delivery used across solidpixels.' version: 1.0.0 servers: - url: 'https://files.app.solidpixels.com' tags: - name: 'Website Files' description: 'Website-scoped file operations.' - name: 'Account Files' description: 'Account-scoped file operations.' - name: 'Component Files' description: 'Component-scoped file operations (internal only).' - name: 'File Serving' description: 'Public endpoints for serving files and on-demand image processing.' components: securitySchemes: default: type: http scheme: bearer description: 'Use a JWT (Bearer token) for authentication.' schemas: DeleteFileResult: type: object properties: id: type: string DeleteFileResultResponse: type: object properties: success: const: true data: $ref: '#/components/schemas/DeleteFileResult' message: type: string required: - success - data DownloadFilesFromUrlRequest: type: object properties: urls: type: array description: 'Array of URLs to download.' items: type: string preserve_original: type: boolean description: 'Preserve the original file.' temporary: type: boolean description: 'Store downloads as temporary files.' expires_at: type: string description: 'Expiry timestamp (ISO 8601 with offset). Requires temporary=true.' required: - urls Error: type: object properties: success: type: boolean message: type: string errors: type: object required: - success - message File: type: object properties: id: type: string maxLength: 35 file_hash: type: - string - 'null' maxLength: 64 file_size: type: integer mime_type: type: string maxLength: 100 storage_path: type: string maxLength: 70 cdn_path: type: - string - 'null' cdn_original_path: type: - string - 'null' serve_path: type: - string - 'null' maxLength: 500 metadata: type: - object - 'null' formats: type: - object - 'null' temporary: type: boolean expires_at: type: - string - 'null' folder: type: - string - 'null' maxLength: 100 created_at: type: string updated_at: type: string required: - id - file_hash - file_size - mime_type - storage_path - cdn_path - cdn_original_path - serve_path - metadata - formats - temporary - expires_at - folder - created_at - updated_at FilePaginatedResponse: type: object properties: success: const: true data: type: array items: $ref: '#/components/schemas/File' message: type: string meta: $ref: '#/components/schemas/PaginationMeta' required: - success - data - meta FileResponse: type: object properties: success: const: true data: $ref: '#/components/schemas/File' message: type: string required: - success - data PaginationMeta: type: object properties: current_page: type: integer last_page: type: integer per_page: type: integer total: type: integer required: - current_page - last_page - per_page - total ScopedFileUploadRequest: type: object properties: files: type: array description: 'Array of binary files to upload.' items: type: string format: binary preserve_original: type: boolean description: 'Preserve the original file.' folder: type: string maxLength: 100 description: 'Folder to group the files under.' serve_paths: type: array description: 'Exact target serve path per file (one entry per file).' items: type: string maxLength: 500 temporary: type: boolean description: 'Store the files as temporary.' expires_at: type: string description: 'Expiry timestamp (ISO 8601 with offset). Requires temporary=true.' required: - files UpdateFileRequest: type: object properties: serve_path: type: string description: 'Maximum 500 characters.' UploadComponentFilesRequest: type: object properties: files: type: array description: 'Array of binary files to upload.' items: type: string format: binary folder: type: string maxLength: 100 description: 'Folder to group the files under.' serve_paths: type: array description: 'Exact target serve path per file (one entry per file).' items: type: string maxLength: 500 temporary: type: boolean description: 'Store the files as temporary.' expires_at: type: string description: 'Expiry timestamp (ISO 8601 with offset). Requires temporary=true.' required: - files UploadResult: type: object properties: filename: type: string maxLength: 500 success: type: boolean created: type: boolean exists: type: boolean file: type: - object - 'null' properties: id: type: string maxLength: 35 file_hash: type: - string - 'null' maxLength: 64 file_size: type: integer mime_type: type: string maxLength: 100 storage_path: type: string maxLength: 70 cdn_path: type: - string - 'null' cdn_original_path: type: - string - 'null' serve_path: type: - string - 'null' maxLength: 500 metadata: type: - object - 'null' formats: type: - object - 'null' temporary: type: boolean expires_at: type: - string - 'null' folder: type: - string - 'null' maxLength: 100 created_at: type: string updated_at: type: string required: - id - file_hash - file_size - mime_type - storage_path - cdn_path - cdn_original_path - serve_path - metadata - formats - temporary - expires_at - folder - created_at - updated_at error: type: - string - 'null' required: - filename - success - created - exists - file - error UploadResultCollectionResponse: type: object properties: success: const: true data: type: array items: $ref: '#/components/schemas/UploadResult' message: type: string required: - success - data ValidationError: type: object properties: success: type: boolean message: type: string errors: type: object required: - success - message - errors responses: Forbidden: description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: 'Internal server error.' content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: 'Not found.' content: application/json: schema: $ref: '#/components/schemas/Error' Unauthenticated: description: Unauthenticated. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationFailed: description: 'Validation failed.' content: application/json: schema: $ref: '#/components/schemas/ValidationError' security: - default: [] paths: /api/v1/websites/files: get: summary: 'List files' operationId: getApiV1WebsitesFiles description: 'Name matching and sorting use the full serve_path. Each stored file appears once, using the lowest-ID matching attachment. Default order: files.created_at DESC, files.id ASC. The default page size is 20, with a maximum of 100.' parameters: - in: query name: page description: 'Page number.' required: false schema: type: integer description: 'Page number.' examples: - 1 - in: query name: per_page description: 'Items per page (max 100).' required: false schema: type: integer description: 'Items per page (max 100).' examples: - 20 default: 20 maximum: 100 - in: query name: folder description: 'Filter by folder.' required: false schema: type: string description: 'Filter by folder.' examples: - ws_acc_x_sess1 - in: query name: serve_path description: 'Filter by exact serve path.' required: false schema: type: string description: 'Filter by exact serve path.' examples: - notes/plan.md - in: query name: 'filter[name]' description: 'Literal, case-insensitive substring of the full serve_path. Blank values are ignored. Maximum 500 characters before trimming.' required: false schema: type: string description: 'Literal, case-insensitive substring of the full serve_path. Blank values are ignored. Maximum 500 characters before trimming.' examples: - banner maxLength: 500 - in: query name: 'filter[mime_type]' description: 'Exact MIME type or trailing type/* family. Use this or the array form.' required: false schema: type: string description: 'Exact MIME type or trailing type/* family. Use this or the array form.' examples: - 'image/*' maxLength: 100 - in: query name: 'filter[mime_type][]' description: 'MIME types or families combined with OR. Other filters combine with AND.' required: false schema: type: array description: 'MIME types or families combined with OR. Other filters combine with AND.' items: type: string maxLength: 100 examples: - - 'image/*' - application/pdf minItems: 1 style: form explode: true - in: query name: sort description: 'Comma-separated name, file_size, or created_at. Prefix a field with - for descending order. Unsupported fields return 422.' required: false schema: type: string description: 'Comma-separated name, file_size, or created_at. Prefix a field with - for descending order. Unsupported fields return 422.' examples: - 'name,-file_size' pattern: '^\s*(?:-?(?:name|file_size|created_at)(?:\s*,\s*-?(?:name|file_size|created_at))*)?\s*$' responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/FilePaginatedResponse' example: success: true data: - id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' - id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' meta: current_page: 1 last_page: 5 per_page: 15 total: 73 message: 'Files retrieved' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Website Files' post: summary: 'Upload files' operationId: postApiV1WebsitesFiles description: 'Uploads files to the website scope.' parameters: [] responses: 200: description: 'All files already existed (no new uploads). Items have `created: false` and `exists: true`.' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files uploaded' 201: description: '' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files uploaded' 207: description: 'Partial success - some uploads failed. Check individual item `success` and `error` fields.' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files uploaded' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Website Files' requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/ScopedFileUploadRequest' '/api/v1/websites/files/{file}': get: summary: 'Get file' operationId: getApiV1WebsitesFilesByFile description: 'Fetch file metadata.' parameters: [] responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/FileResponse' example: success: true data: id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' message: 'File retrieved' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Website Files' put: summary: 'Update file' operationId: putApiV1WebsitesFilesByFile description: 'Update serve path.' parameters: [] responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/FileResponse' example: success: true data: id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' message: 'File updated' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Website Files' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/UpdateFileRequest' delete: summary: 'Delete file' operationId: deleteApiV1WebsitesFilesByFile description: 'Detach or delete a file.' parameters: [] responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteFileResultResponse' example: success: true data: id: fi_gzu16lymnbzh message: 'File deleted successfully' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Website Files' parameters: - in: path name: file description: 'Prefixed file ID (fi_...)' required: true schema: type: string examples: - fi_01jk8mz3x9n7q2w4v6b5 '/api/v1/websites/files/{file}/download': get: summary: 'Download file' operationId: getApiV1WebsitesFilesByFileDownload description: 'Stream file content.' parameters: [] responses: 200: description: '' content: application/octet-stream: schema: type: string format: binary 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Website Files' parameters: - in: path name: file description: 'Prefixed file ID (fi_...)' required: true schema: type: string examples: - fi_01jk8mz3x9n7q2w4v6b5 /api/v1/websites/files/download-from: post: summary: 'Download from URL' operationId: postApiV1WebsitesFilesDownloadFrom description: 'Downloads files from URLs and stores them as website files.' parameters: [] responses: 201: description: '' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files downloaded' 207: description: 'Partial success - some downloads failed.' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files downloaded' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Website Files' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DownloadFilesFromUrlRequest' /api/v1/files: get: summary: 'List files' operationId: getApiV1Files description: 'Name matching and sorting use the full serve_path. Each stored file appears once, using the lowest-ID matching attachment. Default order: files.created_at DESC, files.id ASC. The default page size is 20, with a maximum of 100.' parameters: - in: query name: page description: 'Page number.' required: false schema: type: integer description: 'Page number.' examples: - 1 - in: query name: per_page description: 'Items per page (max 100).' required: false schema: type: integer description: 'Items per page (max 100).' examples: - 20 default: 20 maximum: 100 - in: query name: folder description: 'Filter by folder.' required: false schema: type: string description: 'Filter by folder.' examples: - ws_acc_x_sess1 - in: query name: serve_path description: 'Filter by exact serve path.' required: false schema: type: string description: 'Filter by exact serve path.' examples: - notes/plan.md - in: query name: 'filter[name]' description: 'Literal, case-insensitive substring of the full serve_path. Blank values are ignored. Maximum 500 characters before trimming.' required: false schema: type: string description: 'Literal, case-insensitive substring of the full serve_path. Blank values are ignored. Maximum 500 characters before trimming.' examples: - banner maxLength: 500 - in: query name: 'filter[mime_type]' description: 'Exact MIME type or trailing type/* family. Use this or the array form.' required: false schema: type: string description: 'Exact MIME type or trailing type/* family. Use this or the array form.' examples: - 'image/*' maxLength: 100 - in: query name: 'filter[mime_type][]' description: 'MIME types or families combined with OR. Other filters combine with AND.' required: false schema: type: array description: 'MIME types or families combined with OR. Other filters combine with AND.' items: type: string maxLength: 100 examples: - - 'image/*' - application/pdf minItems: 1 style: form explode: true - in: query name: sort description: 'Comma-separated name, file_size, or created_at. Prefix a field with - for descending order. Unsupported fields return 422.' required: false schema: type: string description: 'Comma-separated name, file_size, or created_at. Prefix a field with - for descending order. Unsupported fields return 422.' examples: - 'name,-file_size' pattern: '^\s*(?:-?(?:name|file_size|created_at)(?:\s*,\s*-?(?:name|file_size|created_at))*)?\s*$' responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/FilePaginatedResponse' example: success: true data: - id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' - id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' meta: current_page: 1 last_page: 5 per_page: 15 total: 73 message: 'Files retrieved' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Website Files' /api/v1/account/files: get: summary: 'List account files' operationId: getApiV1AccountFiles description: 'Name matching and sorting use the full serve_path. Each stored file appears once, using the lowest-ID matching attachment. Default order: files.created_at DESC, files.id ASC. The default page size is 20, with a maximum of 100.' parameters: - in: query name: page description: 'Page number.' required: false schema: type: integer description: 'Page number.' examples: - 1 - in: query name: per_page description: 'Items per page (max 100).' required: false schema: type: integer description: 'Items per page (max 100).' examples: - 20 default: 20 maximum: 100 - in: query name: folder description: 'Filter by folder.' required: false schema: type: string description: 'Filter by folder.' examples: - ws_acc_x_sess1 - in: query name: serve_path description: 'Filter by exact serve path.' required: false schema: type: string description: 'Filter by exact serve path.' examples: - notes/plan.md - in: query name: 'filter[name]' description: 'Literal, case-insensitive substring of the full serve_path. Blank values are ignored. Maximum 500 characters before trimming.' required: false schema: type: string description: 'Literal, case-insensitive substring of the full serve_path. Blank values are ignored. Maximum 500 characters before trimming.' examples: - banner maxLength: 500 - in: query name: 'filter[mime_type]' description: 'Exact MIME type or trailing type/* family. Use this or the array form.' required: false schema: type: string description: 'Exact MIME type or trailing type/* family. Use this or the array form.' examples: - 'image/*' maxLength: 100 - in: query name: 'filter[mime_type][]' description: 'MIME types or families combined with OR. Other filters combine with AND.' required: false schema: type: array description: 'MIME types or families combined with OR. Other filters combine with AND.' items: type: string maxLength: 100 examples: - - 'image/*' - application/pdf minItems: 1 style: form explode: true - in: query name: sort description: 'Comma-separated name, file_size, or created_at. Prefix a field with - for descending order. Unsupported fields return 422.' required: false schema: type: string description: 'Comma-separated name, file_size, or created_at. Prefix a field with - for descending order. Unsupported fields return 422.' examples: - 'name,-file_size' pattern: '^\s*(?:-?(?:name|file_size|created_at)(?:\s*,\s*-?(?:name|file_size|created_at))*)?\s*$' responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/FilePaginatedResponse' example: success: true data: - id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' - id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' meta: current_page: 1 last_page: 5 per_page: 15 total: 73 message: 'Files retrieved' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Account Files' post: summary: 'Upload account files' operationId: postApiV1AccountFiles description: 'Uploads files to the account scope.' parameters: [] responses: 200: description: 'All files already existed (no new uploads). Items have `created: false` and `exists: true`.' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files uploaded' 201: description: '' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files uploaded' 207: description: 'Partial success - some uploads failed. Check individual item `success` and `error` fields.' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files uploaded' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Account Files' requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/ScopedFileUploadRequest' '/api/v1/account/files/{file}': get: summary: 'Get account file' operationId: getApiV1AccountFilesByFile description: 'Fetch file metadata.' parameters: [] responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/FileResponse' example: success: true data: id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' message: 'File retrieved' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Account Files' put: summary: 'Update account file' operationId: putApiV1AccountFilesByFile description: 'Update serve path.' parameters: [] responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/FileResponse' example: success: true data: id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' message: 'File updated' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Account Files' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/UpdateFileRequest' delete: summary: 'Delete account file' operationId: deleteApiV1AccountFilesByFile description: 'Detach or delete a file.' parameters: [] responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteFileResultResponse' example: success: true data: id: fi_gzu16lymnbzh message: 'File deleted successfully' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Account Files' parameters: - in: path name: file description: 'Prefixed file ID (fi_...)' required: true schema: type: string examples: - fi_01jk8mz3x9n7q2w4v6b5 '/api/v1/account/files/{file}/download': get: summary: 'Download account file' operationId: getApiV1AccountFilesByFileDownload description: 'Stream file content.' parameters: [] responses: 200: description: '' content: application/octet-stream: schema: type: string format: binary 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Account Files' parameters: - in: path name: file description: 'Prefixed file ID (fi_...)' required: true schema: type: string examples: - fi_01jk8mz3x9n7q2w4v6b5 /api/v1/account/files/download-from: post: summary: 'Download from URL' operationId: postApiV1AccountFilesDownloadFrom description: 'Downloads files from URLs and stores them as account files.' parameters: [] responses: 201: description: '' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files downloaded' 207: description: 'Partial success - some downloads failed.' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files downloaded' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Account Files' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DownloadFilesFromUrlRequest' '/api/v1/components/{component}/files': get: summary: 'List component files' operationId: getApiV1ComponentsByComponentFiles description: 'Name matching and sorting use the full serve_path. Each stored file appears once, using the lowest-ID matching attachment. Default order: files.created_at DESC, files.id ASC. The default page size is 20, with a maximum of 100.' parameters: - in: query name: page description: 'Page number.' required: false schema: type: integer description: 'Page number.' examples: - 1 - in: query name: per_page description: 'Items per page (max 100).' required: false schema: type: integer description: 'Items per page (max 100).' examples: - 20 default: 20 maximum: 100 - in: query name: folder description: 'Filter by folder.' required: false schema: type: string description: 'Filter by folder.' examples: - ws_acc_x_sess1 - in: query name: serve_path description: 'Filter by exact serve path.' required: false schema: type: string description: 'Filter by exact serve path.' examples: - notes/plan.md - in: query name: 'filter[name]' description: 'Literal, case-insensitive substring of the full serve_path. Blank values are ignored. Maximum 500 characters before trimming.' required: false schema: type: string description: 'Literal, case-insensitive substring of the full serve_path. Blank values are ignored. Maximum 500 characters before trimming.' examples: - banner maxLength: 500 - in: query name: 'filter[mime_type]' description: 'Exact MIME type or trailing type/* family. Use this or the array form.' required: false schema: type: string description: 'Exact MIME type or trailing type/* family. Use this or the array form.' examples: - 'image/*' maxLength: 100 - in: query name: 'filter[mime_type][]' description: 'MIME types or families combined with OR. Other filters combine with AND.' required: false schema: type: array description: 'MIME types or families combined with OR. Other filters combine with AND.' items: type: string maxLength: 100 examples: - - 'image/*' - application/pdf minItems: 1 style: form explode: true - in: query name: sort description: 'Comma-separated name, file_size, or created_at. Prefix a field with - for descending order. Unsupported fields return 422.' required: false schema: type: string description: 'Comma-separated name, file_size, or created_at. Prefix a field with - for descending order. Unsupported fields return 422.' examples: - 'name,-file_size' pattern: '^\s*(?:-?(?:name|file_size|created_at)(?:\s*,\s*-?(?:name|file_size|created_at))*)?\s*$' responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/FilePaginatedResponse' example: success: true data: - id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' - id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' meta: current_page: 1 last_page: 5 per_page: 15 total: 73 message: 'Files retrieved' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Component Files' post: summary: 'Upload component files' operationId: postApiV1ComponentsByComponentFiles description: 'Uploads files to a component scope.' parameters: [] responses: 200: description: 'All files already existed (no new uploads). Items have `created: false` and `exists: true`.' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files uploaded' 201: description: '' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files uploaded' 207: description: 'Partial success - some uploads failed. Check individual item `success` and `error` fields.' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files uploaded' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Component Files' requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/UploadComponentFilesRequest' parameters: - in: path name: component description: 'Component name (e.g., solidpixels, email).' required: true schema: type: string examples: - solidpixels '/api/v1/components/{component}/files/{file}': get: summary: 'Get component file' operationId: getApiV1ComponentsByComponentFilesByFile description: 'Fetch file metadata.' parameters: [] responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/FileResponse' example: success: true data: id: fi_w7hikcnvqf9k file_hash: f7a6b127da0448031eb61c01d6534fbe6cf2f93a7d05b09f06527b0a353c7c5a file_size: 3767452 mime_type: image/webp storage_path: files/948ddf98-4ecf-3d17-b5a6-8c2b6ada81bb.bin cdn_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/original/image.heic' serve_path: assets/atque.webp metadata: width: 2853 height: 281 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_gzu16lymnbzh/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' message: 'File retrieved' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Component Files' delete: summary: 'Delete component file' operationId: deleteApiV1ComponentsByComponentFilesByFile description: 'Detach or delete a file.' parameters: [] responses: 200: description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteFileResultResponse' example: success: true data: id: fi_gzu16lymnbzh message: 'File deleted successfully' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Component Files' parameters: - in: path name: component description: 'Component name.' required: true schema: type: string examples: - solidpixels - in: path name: file description: 'Prefixed file ID (fi_...)' required: true schema: type: string examples: - fi_01jk8mz3x9n7q2w4v6b5 '/api/v1/components/{component}/files/{file}/download': get: summary: 'Download component file' operationId: getApiV1ComponentsByComponentFilesByFileDownload description: 'Stream file content.' parameters: [] responses: 200: description: '' content: application/octet-stream: schema: type: string format: binary 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Component Files' parameters: - in: path name: component description: 'Component name.' required: true schema: type: string examples: - solidpixels - in: path name: file description: 'Prefixed file ID (fi_...)' required: true schema: type: string examples: - fi_01jk8mz3x9n7q2w4v6b5 '/api/v1/components/{component}/files/download-from': post: summary: 'Download from URL' operationId: postApiV1ComponentsByComponentFilesDownloadFrom description: 'Downloads files from URLs and stores them as component files.' parameters: [] responses: 201: description: '' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files downloaded' 207: description: 'Partial success - some downloads failed.' content: application/json: schema: $ref: '#/components/schemas/UploadResultCollectionResponse' example: success: true data: - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null - filename: aspernatur.png success: true created: true exists: false file: id: fi_7hikcnvqf9kx file_hash: 667ca9f46972122ef04a294f379f720c75d417fb3800f7a3ee8253d1215c898f file_size: 10217159 mime_type: image/webp storage_path: files/87732b65-5cce-3609-b973-0cf0e395d6c4.bin cdn_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' cdn_original_path: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/original/image.heic' serve_path: assets/reprehenderit.webp metadata: width: 281 height: 1510 is_animated: false has_transparency: false formats: jpg: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.jpg' webp: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.webp' avif: 'https://cdn.example.com/serve/fat_zu16lymnbzhq/assets/image.avif' temporary: false expires_at: null folder: null created_at: '2026-01-01T00:00:00+00:00' updated_at: '2026-01-01T00:00:00+00:00' error: null message: 'Files downloaded' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 422: $ref: '#/components/responses/ValidationFailed' 500: $ref: '#/components/responses/InternalServerError' tags: - 'Component Files' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DownloadFilesFromUrlRequest' parameters: - in: path name: component description: 'Component name.' required: true schema: type: string examples: - solidpixels '/so/{fileAttachable}/{path}': get: summary: 'Serve file' operationId: getSoByFileAttachableByPath description: "Serves files with optional on-demand image processing via Glide.\n\n**Format conversion**: Change the file extension to convert images (e.g., `.webp`, `.avif`, `.jpg`, `.png`).\n\n**Image manipulation**: Add query parameters to resize, crop, adjust colors, and apply effects to processable images (JPEG, PNG, GIF, WebP, BMP, TIFF, HEIC/HEIF).\n\n**Original files**: Use `/so/{fileAttachable}/{path}` to serve the pre-conversion original file without any processing.\n\nNon-image files and non-processable images are served directly without modification." parameters: - in: query name: w description: 'Width in pixels.' required: false schema: type: integer description: 'Width in pixels.' examples: - 800 - in: query name: h description: 'Height in pixels.' required: false schema: type: integer description: 'Height in pixels.' examples: - 600 - in: query name: fit description: 'Fit mode: contain, max, fill, stretch, crop.' required: false schema: type: string description: 'Fit mode: contain, max, fill, stretch, crop.' examples: - contain - in: query name: crop description: 'Crop position: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right, or custom coordinates.' required: false schema: type: string description: 'Crop position: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right, or custom coordinates.' examples: - center - in: query name: dpr description: 'Device pixel ratio (1-8).' required: false schema: type: integer description: 'Device pixel ratio (1-8).' examples: - 2 - in: query name: q description: 'Quality (1-100). Only applies to lossy formats.' required: false schema: type: integer description: 'Quality (1-100). Only applies to lossy formats.' examples: - 85 - in: query name: or description: 'Orientation: auto, 0, 90, 180, 270.' required: false schema: type: string description: 'Orientation: auto, 0, 90, 180, 270.' examples: - auto - in: query name: flip description: 'Flip: v (vertical), h (horizontal), both.' required: false schema: type: string description: 'Flip: v (vertical), h (horizontal), both.' examples: - h - in: query name: bri description: 'Brightness adjustment (-100 to 100).' required: false schema: type: integer description: 'Brightness adjustment (-100 to 100).' examples: - 10 - in: query name: con description: 'Contrast adjustment (-100 to 100).' required: false schema: type: integer description: 'Contrast adjustment (-100 to 100).' examples: - 10 - in: query name: gam description: 'Gamma correction (0.1 to 9.99).' required: false schema: type: number description: 'Gamma correction (0.1 to 9.99).' examples: - 1.2 - in: query name: sharp description: 'Sharpen amount (0-100).' required: false schema: type: integer description: 'Sharpen amount (0-100).' examples: - 15 - in: query name: blur description: 'Blur amount (0-100).' required: false schema: type: integer description: 'Blur amount (0-100).' examples: - 5 - in: query name: pixel description: 'Pixelate amount (0-1000).' required: false schema: type: integer description: 'Pixelate amount (0-1000).' examples: - 10 - in: query name: filt description: 'Filter: greyscale, sepia.' required: false schema: type: string description: 'Filter: greyscale, sepia.' examples: - greyscale - in: query name: bg description: 'Background color (hex). Used when fit creates padding.' required: false schema: type: string description: 'Background color (hex). Used when fit creates padding.' examples: - ffffff - in: query name: border description: 'Border: width,color,method (e.g., "5,ffffff,overlay").' required: false schema: type: string description: 'Border: width,color,method (e.g., "5,ffffff,overlay").' examples: - '5,000000,overlay' - in: query name: p description: 'Preset name (as configured in server).' required: false schema: type: string description: 'Preset name (as configured in server).' examples: - aspernatur - in: query name: s description: 'Signature for signed URLs (when signature validation is enabled).' required: false schema: type: string description: 'Signature for signed URLs (when signature validation is enabled).' examples: - aspernatur responses: 200: description: 'Image served successfully.' content: text/plain: schema: type: string examples: - '<>' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'File Serving' parameters: - in: path name: fileAttachable description: 'Prefixed file-attachable ID (fat_...).' required: true schema: type: string examples: - fat_abc123xyz - in: path name: path description: 'Serve path of the file. Change extension for format conversion.' required: true schema: type: string examples: - assets/logo.webp '/s/{fileAttachable}/{path}': get: summary: 'Serve file' operationId: getSByFileAttachableByPath description: "Serves files with optional on-demand image processing via Glide.\n\n**Format conversion**: Change the file extension to convert images (e.g., `.webp`, `.avif`, `.jpg`, `.png`).\n\n**Image manipulation**: Add query parameters to resize, crop, adjust colors, and apply effects to processable images (JPEG, PNG, GIF, WebP, BMP, TIFF, HEIC/HEIF).\n\n**Original files**: Use `/so/{fileAttachable}/{path}` to serve the pre-conversion original file without any processing.\n\nNon-image files and non-processable images are served directly without modification." parameters: - in: query name: w description: 'Width in pixels.' required: false schema: type: integer description: 'Width in pixels.' examples: - 800 - in: query name: h description: 'Height in pixels.' required: false schema: type: integer description: 'Height in pixels.' examples: - 600 - in: query name: fit description: 'Fit mode: contain, max, fill, stretch, crop.' required: false schema: type: string description: 'Fit mode: contain, max, fill, stretch, crop.' examples: - contain - in: query name: crop description: 'Crop position: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right, or custom coordinates.' required: false schema: type: string description: 'Crop position: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right, or custom coordinates.' examples: - center - in: query name: dpr description: 'Device pixel ratio (1-8).' required: false schema: type: integer description: 'Device pixel ratio (1-8).' examples: - 2 - in: query name: q description: 'Quality (1-100). Only applies to lossy formats.' required: false schema: type: integer description: 'Quality (1-100). Only applies to lossy formats.' examples: - 85 - in: query name: or description: 'Orientation: auto, 0, 90, 180, 270.' required: false schema: type: string description: 'Orientation: auto, 0, 90, 180, 270.' examples: - auto - in: query name: flip description: 'Flip: v (vertical), h (horizontal), both.' required: false schema: type: string description: 'Flip: v (vertical), h (horizontal), both.' examples: - h - in: query name: bri description: 'Brightness adjustment (-100 to 100).' required: false schema: type: integer description: 'Brightness adjustment (-100 to 100).' examples: - 10 - in: query name: con description: 'Contrast adjustment (-100 to 100).' required: false schema: type: integer description: 'Contrast adjustment (-100 to 100).' examples: - 10 - in: query name: gam description: 'Gamma correction (0.1 to 9.99).' required: false schema: type: number description: 'Gamma correction (0.1 to 9.99).' examples: - 1.2 - in: query name: sharp description: 'Sharpen amount (0-100).' required: false schema: type: integer description: 'Sharpen amount (0-100).' examples: - 15 - in: query name: blur description: 'Blur amount (0-100).' required: false schema: type: integer description: 'Blur amount (0-100).' examples: - 5 - in: query name: pixel description: 'Pixelate amount (0-1000).' required: false schema: type: integer description: 'Pixelate amount (0-1000).' examples: - 10 - in: query name: filt description: 'Filter: greyscale, sepia.' required: false schema: type: string description: 'Filter: greyscale, sepia.' examples: - greyscale - in: query name: bg description: 'Background color (hex). Used when fit creates padding.' required: false schema: type: string description: 'Background color (hex). Used when fit creates padding.' examples: - ffffff - in: query name: border description: 'Border: width,color,method (e.g., "5,ffffff,overlay").' required: false schema: type: string description: 'Border: width,color,method (e.g., "5,ffffff,overlay").' examples: - '5,000000,overlay' - in: query name: p description: 'Preset name (as configured in server).' required: false schema: type: string description: 'Preset name (as configured in server).' examples: - aspernatur - in: query name: s description: 'Signature for signed URLs (when signature validation is enabled).' required: false schema: type: string description: 'Signature for signed URLs (when signature validation is enabled).' examples: - aspernatur responses: 200: description: 'Image served successfully.' content: text/plain: schema: type: string examples: - '<>' 401: $ref: '#/components/responses/Unauthenticated' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' tags: - 'File Serving' parameters: - in: path name: fileAttachable description: 'Prefixed file-attachable ID (fat_...).' required: true schema: type: string examples: - fat_abc123xyz - in: path name: path description: 'Serve path of the file. Change extension for format conversion.' required: true schema: type: string examples: - assets/logo.webp