> ## Documentation Index > Fetch the complete documentation index at: https://dify-6c0370d8-fix-template-upload-size-guidance.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Upload File > **Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps. Uploads a file and returns its `id` for later requests to reference. The file belongs to the uploading end user: only requests carrying the same `user` can reference it. Which file types an app actually consumes depends on its file-upload settings; read them from [Get App Parameters](/en/api-reference/applications/get-app-parameters). ## OpenAPI ````yaml /en/api-reference/openapi_service.json post /files/upload openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline paths: /files/upload: post: tags: - Files summary: Upload File description: >- **Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps. Uploads a file and returns its `id` for later requests to reference. The file belongs to the uploading end user: only requests carrying the same `user` can reference it. Which file types an app actually consumes depends on its file-upload settings; read them from [Get App Parameters](/en/api-reference/applications/get-app-parameters). operationId: uploadChatFile requestBody: content: multipart/form-data: schema: properties: file: description: >- The file to upload, as one `multipart/form-data` part. The filename must not contain `/` or `\`. Any extension is accepted unless it is on the deployment's security blacklist (`UPLOAD_FILE_EXTENSION_BLACKLIST`, empty by default). Size limits per category: images 10 MB, audio 50 MB, video 100 MB, other files 15 MB by default (Dify Cloud uses the defaults). Self-hosted deployments adjust them with the `UPLOAD_*_FILE_SIZE_LIMIT` [environment variables](/en/self-host/deploy/configuration/environments). format: binary type: string user: description: >- End-user identifier this upload belongs to, defined by your app and unique within it. Omit it to attribute the upload to the shared `DEFAULT-USER`. Only later requests with the same `user` can reference the file. See [End User Identity](/en/api-reference/guides/end-user-identity). type: string required: - file type: object description: File upload request. Requires multipart/form-data. required: true responses: '201': content: application/json: examples: uploadSuccess: summary: Response Example value: conversation_id: null created_at: 1705407629 created_by: f1e2d3c4-b5a6-7890-abcd-ef1234567890 extension: png file_key: null id: a1b2c3d4-5678-90ab-cdef-1234567890ab mime_type: image/png name: product-photo.png original_url: null preview_url: null reference: null size: 204800 source_url: >- https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI= tenant_id: 11223344-5566-7788-99aa-bbccddeeff00 user_id: null schema: $ref: '#/components/schemas/FileUploadResponse' description: File uploaded successfully. '400': content: application/json: examples: filename_not_exists_error: summary: filename_not_exists_error value: code: filename_not_exists_error message: The specified filename does not exist. status: 400 invalid_param: summary: invalid_param value: code: invalid_param message: File extension '.exe' is not allowed for security reasons status: 400 no_file_uploaded: summary: no_file_uploaded value: code: no_file_uploaded message: Please upload your file. status: 400 too_many_files: summary: too_many_files value: code: too_many_files message: Only one file is allowed. status: 400 description: >- - `no_file_uploaded` : No file was provided in the request. - `too_many_files` : Only one file is allowed per request. - `filename_not_exists_error` : The uploaded file has no filename. - `invalid_param` : The filename contains `/` or `\`, or the file's extension is on the deployment's blacklist. '413': content: application/json: examples: file_too_large: summary: file_too_large value: code: file_too_large message: '' status: 413 description: >- `file_too_large` : The file exceeds its category's size limit (see the `file` field). The runtime `message` is currently returned as an empty string (a known backend quirk); rely on the `code` and status. '415': content: application/json: examples: unsupported_file_type: summary: unsupported_file_type value: code: unsupported_file_type message: File type not allowed. status: 415 description: >- `unsupported_file_type` : The uploaded `file` part declares no MIME type. components: schemas: FileUploadResponse: properties: conversation_id: description: ID of the associated conversation. format: uuid nullable: true type: string created_at: description: Upload timestamp (Unix epoch seconds). format: int64 type: integer created_by: description: >- End-user ID of the uploader. Look up details with [Get End User Info](/en/api-reference/end-users/get-end-user-info). format: uuid nullable: true type: string extension: description: File extension. nullable: true type: string file_key: description: Unused; always `null`. nullable: true type: string id: description: Unique file ID. format: uuid type: string mime_type: description: MIME type of the file. nullable: true type: string name: description: File name. type: string original_url: description: Original URL of the file. nullable: true type: string preview_url: description: Preview URL for the file. nullable: true type: string reference: description: >- Opaque file reference used internally when attaching files in agent and tool contexts. Always `null` for files uploaded through this endpoint. nullable: true type: string size: description: File size in bytes. type: integer source_url: description: Signed URL for downloading the file. type: string tenant_id: description: ID of the associated tenant. format: uuid nullable: true type: string user_id: description: Unused; always `null`. format: uuid nullable: true type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ````