Dify Files API
File upload and preview operations. 2 operation(s) from the Dify Service API.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/dify-files-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.0.1
info:
title: Dify Files API
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.
version: 1.0.0
servers:
- url: https://{api_base_url}
description: Base URL of the Dify Service API. For self-hosted deployments, replace it with your own
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:
- name: Files
description: File upload and preview operations.
paths:
/files/upload:
post:
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
tags:
- Files
requestBody:
description: File upload request. Requires multipart/form-data.
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
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).'
user:
type: string
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).
responses:
'201':
description: File uploaded successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FileUploadResponse'
examples:
uploadSuccess:
summary: Response Example
value:
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://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
'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.'
content:
application/json:
examples:
no_file_uploaded:
summary: no_file_uploaded
value:
status: 400
code: no_file_uploaded
message: Please upload your file.
too_many_files:
summary: too_many_files
value:
status: 400
code: too_many_files
message: Only one file is allowed.
filename_not_exists_error:
summary: filename_not_exists_error
value:
status: 400
code: filename_not_exists_error
message: The specified filename does not exist.
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: File extension '.exe' is not allowed for security reasons
'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.'
content:
application/json:
examples:
file_too_large:
summary: file_too_large
value:
status: 413
code: file_too_large
message: ''
'415':
description: '`unsupported_file_type` : The uploaded `file` part declares no MIME type.'
content:
application/json:
examples:
unsupported_file_type:
summary: unsupported_file_type
value:
status: 415
code: unsupported_file_type
message: File type not allowed.
x-mint:
href: /en/api-reference/files/upload-file
metadata:
title: Upload File
sidebarTitle: Upload File
/files/{file_id}/preview:
get:
summary: Download File
description: '**Available for**: Chatflow, Chatbot, Legacy Agent, Text Generator apps.
Returns the raw bytes of a file previously returned by [Upload File](/en/api-reference/files/upload-file).
A file is reachable only through the app whose messages reference it.'
operationId: previewChatFile
tags:
- Files
parameters:
- name: file_id
in: path
required: true
description: ID of the file to download, from the Upload File response.
schema:
type: string
format: uuid
- name: as_attachment
in: query
required: false
description: When `true`, the file downloads as an attachment instead of rendering inline in the
browser.
schema:
type: boolean
default: false
- name: user
in: query
required: false
description: End-user identifier, defined by your app and unique within it. It has no effect on
file access here, which is scoped by app and message rather than by `user`. See [End User Identity](/en/api-reference/guides/end-user-identity).
schema:
type: string
responses:
'200':
description: 'Returns the raw file content. The `Content-Type` header is set to the file''s
MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition:
attachment`.'
content:
application/octet-stream:
schema:
type: string
format: binary
'403':
description: '`file_access_denied` : The file exists but belongs to a different app or workspace.'
content:
application/json:
examples:
file_access_denied:
summary: file_access_denied
value:
status: 403
code: file_access_denied
message: Access to the requested file is denied.
'404':
description: '`file_not_found` : No file with this ID is reachable through this app''s messages.'
content:
application/json:
examples:
file_not_found:
summary: file_not_found
value:
status: 404
code: file_not_found
message: The requested file was not found.
x-mint:
href: /en/api-reference/files/download-file
metadata:
title: Download File
sidebarTitle: Download File
components:
schemas:
FileUploadResponse:
type: object
properties:
id:
type: string
format: uuid
description: Unique file ID.
reference:
type: string
nullable: true
description: Opaque file reference used internally when attaching files in agent and tool contexts.
Always `null` for files uploaded through this endpoint.
name:
type: string
description: File name.
size:
type: integer
description: File size in bytes.
extension:
type: string
nullable: true
description: File extension.
mime_type:
type: string
nullable: true
description: MIME type of the file.
created_by:
type: string
format: uuid
nullable: true
description: 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:
type: integer
format: int64
description: Upload timestamp (Unix epoch seconds).
preview_url:
type: string
nullable: true
description: Preview URL for the file.
source_url:
type: string
description: Signed URL for downloading the file.
original_url:
type: string
nullable: true
description: Original URL of the file.
user_id:
type: string
format: uuid
nullable: true
description: Unused; always `null`.
tenant_id:
type: string
format: uuid
nullable: true
description: ID of the associated tenant.
conversation_id:
type: string
format: uuid
nullable: true
description: ID of the associated conversation.
file_key:
type: string
nullable: true
description: Unused; always `null`.
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
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`).'
x-provenance:
generated: '2026-09-06'
method: derived
source: openapi/_original/dify-service-api-openapi.json
note: Per-tag split of the first-party Dify Service API OpenAPI harvested from https://docs.dify.ai/en/api-reference/openapi_service.json
(advertised in https://docs.dify.ai/llms.txt). Paths, schemas and operationIds are verbatim from that
spec.