---
title: "Upload File"
method: POST
path: "/files/upload"
tags: ["Files"]
---

# Upload File

`POST /files/upload`

**Available for**: Chatflow, Workflow, New Agent, Chatbot, 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).

## Response `201`

File uploaded successfully.

- FileUploadResponse
  - `id` string, uuid — Unique file ID.
  - `reference` string, nullable — Opaque file reference used internally when attaching files in agent and tool contexts. Always `null` for files uploaded through this endpoint.
  - `name` string — File name.
  - `size` integer — File size in bytes.
  - `extension` string, nullable — File extension.
  - `mime_type` string, nullable — MIME type of the file.
  - `created_by` string, uuid, nullable — End-user ID of the uploader. Look up details with [Get End User Info](/en/api-reference/end-users/get-end-user-info).
  - `created_at` integer — Upload timestamp (Unix epoch seconds).
  - `preview_url` string, nullable — Preview URL for the file.
  - `source_url` string — Signed URL for downloading the file.
  - `original_url` string, nullable — Original URL of the file.
  - `user_id` string, uuid, nullable — Unused; always `null`.
  - `tenant_id` string, uuid, nullable — ID of the associated tenant.
  - `conversation_id` string, uuid, nullable — ID of the associated conversation.
  - `file_key` string, nullable — Unused; always `null`.

## Other responses

- `400` — - `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` — `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` — `unsupported_file_type` : The uploaded `file` part declares no MIME type.

---

[API](https://skmtc.net/langgenius/apis/dify-service-api.md) · [All operations](https://skmtc.net/langgenius/apis/dify-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/langgenius/dify-service-api/revisions/e49b3db72bad/schema)