Upload File

curl --request POST \
  --url https://{deployed_api_base_url}/v2/files/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form 'user=<string>'

import requests

url = "https://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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",
  "reference": null,
  "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://api.example.com/files/appdeploy/a1b2c3d4-5678-90ab-cdef-1234567890ab/content?token=eyJhbGciOiJIUzI1NiJ9.example",
  "original_url": null,
  "user_id": null,
  "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "conversation_id": null,
  "file_key": null
}

Deployed Environments

Upload File

Available for: Workflow, Chatflow

Uploads a file for use in requests to this app in this environment.

The returned id works only for requests that carry the same user, to the same app and environment. A single run can reference at most 100 files.

Standard API equivalent: Upload File. Differences:

user is required.
The response’s source_url is a signed download URL.
The combined size of all parts arriving before the user field is capped at 100 MiB.
Error codes differ.

POST

files

upload

Upload File

curl --request POST \
  --url https://{deployed_api_base_url}/v2/files/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form 'user=<string>'

import requests

url = "https://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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://{deployed_api_base_url}/v2/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",
  "reference": null,
  "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://api.example.com/files/appdeploy/a1b2c3d4-5678-90ab-cdef-1234567890ab/content?token=eyJhbGciOiJIUzI1NiJ9.example",
  "original_url": null,
  "user_id": null,
  "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "conversation_id": null,
  "file_key": null
}

Authorizations

Authorization

string

header

required

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).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Body

multipart/form-data

file

required

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).

Default size limits per category: images 5 MB, audio 50 MB, video 100 MB, other files 15 MB. Your platform administrator can change them with the UPLOAD_*_FILE_SIZE_LIMIT environment variables.

user

string

required

End-user identifier, defined by your app and unique within it. The file belongs to this user in this app and environment. Send this part before the file part when possible; the combined size of parts arriving before it is capped at 100 MiB. See End User Identity.

Maximum string length: 512

Response

The stored file, with the id to reference in a run.

string<uuid>

Unique file ID.

reference

string | null

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 | null

File extension.

mime_type

string | null

MIME type of the file.

created_by

string<uuid> | null

End-user ID of the uploader. Look up details with Get End User Info.

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.

Guides

App APIs

Knowledge APIs

Upload File

Authorizations

Body

Response