Skip to main content
POST
/
files
/
upload
Upload File
curl --request POST \
  --url https://{api_base_url}/files/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'user=<string>'
import requests

url = "https://{api_base_url}/files/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "user": "<string>" }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)
const form = new FormData();
form.append('file', '<string>');
form.append('user', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://{api_base_url}/files/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_base_url}/files/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"user\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_base_url}/files/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"user\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://{api_base_url}/files/upload")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"user\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://{api_base_url}/files/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"user\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "product-photo.png",
  "size": 204800,
  "extension": "png",
  "mime_type": "image/png",
  "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "created_at": 1705407629,
  "preview_url": null,
  "source_url": "https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI=",
  "original_url": null,
  "user_id": null,
  "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "conversation_id": null,
  "file_key": null
}

Authorizations

​
Authorization
string
header
required

API Key authentication. For all API requests, include your API Key in the Authorization HTTP Header, prefixed with Bearer. Example: Authorization: Bearer {API_KEY}. Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences. Requests with a missing or invalid API key fail with HTTP 401 and error code unauthorized.

Body

multipart/form-data

File upload request. Requires multipart/form-data.

​
file
file
required

The file to be uploaded. Supported types include images, documents, audio, and video.

​
user
string

Identifier for the end user, defined by your application's rules and unique within the app. Service API and WebApp user IDs are separate, even when identical. If omitted, the upload is attributed to the shared DEFAULT-USER end user; a file can only be used later by requests carrying the same user value.

Response

File uploaded successfully.

​
id
string<uuid>

Unique file ID.

​
name
string

File name.

​
size
integer

File size in bytes.

​
extension
string | null

File extension.

​
mime_type
string | null

MIME type of the file.

​
created_by
string<uuid> | null

ID of the user who uploaded the file.

​
created_at
integer<int64>

Upload timestamp (Unix epoch seconds).

​
preview_url
string | null

Preview URL for the file.

​
source_url
string

Signed URL for downloading the file.

​
original_url
string | null

Original URL of the file.

​
user_id
string<uuid> | null

Unused; always null.

​
tenant_id
string<uuid> | null

ID of the associated tenant.

​
conversation_id
string<uuid> | null

ID of the associated conversation.

​
file_key
string | null

Unused; always null.

Last modified on July 9, 2026