Skip to main content

File management

Upload, list, download, and delete files using the DIAL Core File Storage Management API. This guide is for developers who call the Unified API directly. You should know how to authenticate with an API key or JWT and how to send HTTP requests with a tool such as curl.

Every file in DIAL lives in a bucket — the private storage space of a user or a deployment. You address a file by combining the bucket identifier with a path inside that bucket. Before you can read or write files, you need your bucket identifier.

Prerequisites​

  • A running DIAL deployment and its base URL, referred to below as <DIAL_URL>.
  • An API key or a JWT with permission to access file storage.

Authentication​

Send your credentials with every request, using one of these headers:

# With an API key
-H "Api-Key: <YOUR_DIAL_API_KEY>"

# With a JWT
-H "Authorization: Bearer <YOUR_JWT>"

The examples below use an API key. Substitute the JWT header if you authenticate with a token.

Step 1: Get your bucket​

Call GET /v1/bucket to retrieve the identifier of your storage bucket. Every file path you build afterwards starts with this value.

curl "<DIAL_URL>/v1/bucket" \
  -H "Api-Key: <YOUR_DIAL_API_KEY>"

The response contains the encrypted bucket identifier:

{
  "bucket": "<BUCKET_ID>",
  "appdata": null
}

The appdata field is null for ordinary requests. It is populated only when the request is made with a per-request key issued to a deployment, in which case it points to the deployment's writable folder in the user's bucket.

note

The bucket identifier is an opaque, encrypted string. Use the value returned by GET /v1/bucket as-is; do not construct it yourself.

Step 2: Upload a file​

Upload a file with PUT /v1/files/{bucket}/{path}. The request body is multipart/form-data, and {path} is the destination path inside your bucket, ending with the file name.

curl -X PUT "<DIAL_URL>/v1/files/<BUCKET_ID>/my-folder/report.pdf" \
  -H "Api-Key: <YOUR_DIAL_API_KEY>" \
  -F "file=@report.pdf"

A successful upload returns 200 with the file metadata and an ETag header:

{
  "name": "report.pdf",
  "parentPath": "my-folder",
  "bucket": "<BUCKET_ID>",
  "url": "files/<BUCKET_ID>/my-folder/report.pdf",
  "nodeType": "ITEM",
  "resourceType": "FILE",
  "contentType": "application/pdf",
  "contentLength": 184320,
  "etag": "<ETAG>",
  "createdAt": 1717000000000,
  "updatedAt": 1717000000000
}

Issuing the same request again overwrites the file. To guard against overwriting a version you have not seen, pass the ETag you last received in an If-Match header; DIAL Core returns 412 Precondition Failed if the stored version differs.

warning

The maximum upload size is controlled by the storage.maxUploadedFileSize setting in DIAL Core (default 512 MiB). A larger file is rejected with HTTP 413 Payload Too Large.

Step 3: List files​

List the contents of a folder with GET /v1/metadata/files/{bucket}/{path}. Use a trailing slash to address a folder; an empty path lists the bucket root.

curl "<DIAL_URL>/v1/metadata/files/<BUCKET_ID>/my-folder/" \
  -H "Api-Key: <YOUR_DIAL_API_KEY>"

The response lists the immediate children of the folder:

{
  "name": "my-folder",
  "bucket": "<BUCKET_ID>",
  "url": "files/<BUCKET_ID>/my-folder/",
  "nodeType": "FOLDER",
  "resourceType": "FILE",
  "items": [
    {
      "name": "report.pdf",
      "parentPath": "my-folder",
      "bucket": "<BUCKET_ID>",
      "url": "files/<BUCKET_ID>/my-folder/report.pdf",
      "nodeType": "ITEM",
      "resourceType": "FILE",
      "contentType": "application/pdf",
      "contentLength": 184320
    }
  ]
}

The metadata endpoint accepts these query parameters:

ParameterTypeDefaultDescription
recursivebooleanfalseWhen true, lists all descendants instead of only immediate children.
limitinteger100Maximum number of items to return. Must be between 0 and 1000.
tokenstring—Continuation token from a previous response, used to fetch the next page.

When the result is truncated, the response includes a nextToken value. Pass it as token on the next request to continue paging.

Step 4: Download a file​

Retrieve the raw file bytes with GET /v1/files/{bucket}/{path}.

curl "<DIAL_URL>/v1/files/<BUCKET_ID>/my-folder/report.pdf" \
  -H "Api-Key: <YOUR_DIAL_API_KEY>" \
  -o report.pdf

The response body is the file content, served with the Content-Type stored at upload time.

Step 5: Delete a file​

Remove a file with DELETE /v1/files/{bucket}/{path}.

curl -X DELETE "<DIAL_URL>/v1/files/<BUCKET_ID>/my-folder/report.pdf" \
  -H "Api-Key: <YOUR_DIAL_API_KEY>"

A successful deletion returns 200. Deleting a file that does not exist returns 404.

Result​

You can now create your bucket address, upload and overwrite files, page through folder listings, download content, and delete files. These operations underpin attachments in conversations, RAG document stores, and any application that persists user data.

Further reading​