# 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="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-c69024a461fc2171c78bfa97f9037eceff5e3950%2Fupload_action.png?alt=media" 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](https://docs.digia.tech/logic-and-interaction/actions/file-picker) - Select files to upload
* [Image Picker](https://docs.digia.tech/logic-and-interaction/actions/image-picker) - Select images/videos for upload
* [Call Rest API](https://docs.digia.tech/logic-and-interaction/actions/call-rest-api) - General API communication
* [Set State](https://docs.digia.tech/logic-and-interaction/actions/set-state) - Update UI state with upload results

***

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