# Upload

The **Upload Files** action allows you to upload one or more files to a remote API endpoint. It provides full control over the upload stream and supports custom success and error handling, along with advanced options like cancel tokens and stream controllers.

## Properties

| Property            | Type                 | Required | Description                                                        |
| ------------------- | -------------------- | -------- | ------------------------------------------------------------------ |
| `API Call`          | Dropdown and value   | ✅        | Select API call from dropdown and fill their respective API params |
| `Success Condition` | Expression (Boolean) | ❌        | Optional expression to determine if the upload was successful      |
| `On Success`        | Action Flow          | ❌        | Actions to execute when upload succeeds                            |
| `On Error`          | Action Flow          | ❌        | Actions to execute when upload fails                               |
| `Stream Controller` | Dropdown             | ❌        | Select stream controller variable to track upload progress         |
| `Cancel Token`      | Dropdown             | ❌        | Select cancel token variable to allow upload cancellation          |

## Use Cases

* **File Sharing**: Upload user-selected files to cloud storage
* **Media Upload**: Send images, videos, or audio files to servers
* **Document Processing**: Submit documents for processing or storage
* **Form Submissions**: Upload files as part of form data
* **Backup Services**: Send files to backup or archive services

## Default Behavior

By default:

| Behavior               | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Request Format**     | Uses multipart/form-data for file uploads                     |
| **Success Evaluation** | All responses treated as successful if no condition specified |
| **Progress Tracking**  | Progress events emitted when stream controller provided       |
| **Cancellation**       | Upload can be cancelled using provided cancel token           |
| **Response Access**    | Upload response available as `{{response}}` in action flows   |

## How to Use

<figure><img src="/files/hd5dH9E4Sz36JBAYPjQZ" alt="Upload action configuration"><figcaption><p>Upload action configuration in Digia Studio</p></figcaption></figure>

1. Attach the action to a widget event (file selection, form submission, etc.)
2. Select **Upload** from the action list
3. Select `API Call` from dropdown and fill their respective params
4. Set optional `Success Condition` to define success criteria
5. Define `On Success` and `On Error` action flows as needed
6. Use `Stream Controller` for progress tracking if required
7. Use `Cancel Token` for upload cancellation if needed

## Implementation Details

The action uses Dio for HTTP requests and sends files as multipart/form-data. The response object contains:

| Field        | Description                                  |
| ------------ | -------------------------------------------- |
| `body`       | Response body data                           |
| `statusCode` | HTTP status code                             |
| `headers`    | Response headers map                         |
| `requestObj` | Request details (URL, method, headers, data) |
| `error`      | Error message (null for successful uploads)  |

**Success Condition Examples:**

* `isEqual(response.statusCode, 200)` - Success only on HTTP 200
* `and(gte(response.statusCode, 200), lt(response.statusCode, 300))` - Success on 2xx status codes
* `isEqual(jsonGet(response.body, 'success'), true)` - Success based on response body content

## Related Actions

* [File Picker](/logic-and-interaction/actions/file-picker.md) - Select files to upload
* [Image Picker](/logic-and-interaction/actions/image-picker.md) - Select images/videos for upload
* [Call Rest API](/logic-and-interaction/actions/call-rest-api.md) - General API communication
* [Set State](/logic-and-interaction/actions/set-state.md) - Update UI state with upload results

***

*Asset Placeholder: Tutorial video demonstrating file upload workflows and progress tracking in Digia Studio*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/logic-and-interaction/actions/upload.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.