> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# Swift API Client for Uploadcare

> Swift Uploadcare API client for Fast & Reliable File Uploads; File, Group, Project Operations; Video + Document Conversion; File Uploader integration.

Swift integration handles uploads and file operations by wrapping Uploadcare
[Upload API](https://uploadcare.com/docs/api/upload/) and [REST API](https://uploadcare.com/docs/api/rest/). This
comprehensive API client lets you use most of the Uploadcare features, including a native uploading widget.
Builds are available for iOS, iPadOS, tvOS, Linux and macOS.

[GitHub →](https://github.com/uploadcare/uploadcare-swift)

Check out a [swift demo app](https://github.com/uploadcare/uploadcare-swift/tree/master/Demo) that we created as a showcase for
various usage scenarios and tasks that you can resolve.

## Features

Uploading ([Upload API](https://uploadcare.com/docs/api/upload/)):

* Upload files from a file, URL, and cloud sources (up to 5 TB)
* Multipart uploading for large files
* Uploading network to speed uploading jobs (like CDN)

File uploading widget:

* Upload files from a local disk, camera, and cloud sources
* Track, pause and continue multipart uploading
* Background uploading
* Bulk file uploading

File management ([REST API](https://uploadcare.com/docs/api/rest/)):

* Get file info and perform various operations (store/delete/copy) with them
* Work with groups of files
* Get info about account project
* Manage webhooks
* Convert documents
* Encode and transform videos

Image processing ([URL API](https://uploadcare.com/docs/api/url/)):

* Compression
* Geometry
* Colors
* Definition
* Image and text overlays
* Rotations
* Recognition
* File info
* Proxy (fetch)

Security features:

* Secure authentication
* Secure uploads (signed uploads)
* Secure delivery (signed URLs)
* Secure webhooks (signing secret)

## Installation

### Swift Package Manager

To use a stable version, add a dependency to your `Package.swift` file:

```swift
dependencies: [
    .package(url: "https://github.com/uploadcare/uploadcare-swift.git", from: "0.14.0")
]
```

If you want to try the current dev version, change the dependency to:

```swift
dependencies: [
    .package(url: "https://github.com/uploadcare/uploadcare-swift.git", branch: "develop")
]
```

To add from Xcode select File -> Swift Packages -> Add Package Dependency and
enter the repository URL:

`https://github.com/uploadcare/uploadcare-swift`

Or you can add it in Xcode to the packages list using that URL: `https://github.com/uploadcare/uploadcare-swift`
and set the dependency rule to **Up to Next Major Version** with `0.14.0` as the minimum version.

### Carthage

To use a stable version, add a dependency to your Cartfile:

```
github "uploadcare/uploadcare-swift"
```

To use the current dev version:

```
github "uploadcare/uploadcare-swift" "develop"
```

### Cocoapods

To use a stable version, add a dependency to your Podfile:

```
pod 'Uploadcare', git: 'https://github.com/uploadcare/uploadcare-swift'
```

To use current dev version:

```
pod 'Uploadcare', git: 'https://github.com/uploadcare/uploadcare-swift', :branch => 'develop'
```

> **Note**
>
> **Note:** The `UploadcareWidget` SwiftUI file picker is available via Swift Package Manager only. CocoaPods installs the core client without the widget.

## Initialization

Create your project in [Uploadcare Dashboard](https://app.uploadcare.com/) and copy its
[API keys](https://app.uploadcare.com/projects/-/api-keys/) from there.

Upload API requires only a public key, while REST API requires both public and secret keys:

```swift
final class MyClass {
    private var uploadcare: Uploadcare

    init() {
        self.uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY")

        // Secret key is optional if you want to use Upload API only
        // REST API requires both public and secret keys:
        self.uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")
    }
}
```

You can create more Uploadcare objects if you need to work with multiple projects
in your Uploadcare account:

```swift
final class MyClass {
    private let project1: Uploadcare
    private let project2: Uploadcare

    init() {
        // A project to use Upload API only
        self.project1 = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY_1")

        // A project to use both REST API and Upload API
        self.project2 = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY_2", secretKey: "YOUR_SECRET_KEY_2")
    }
}
```

Keep in mind that since Uploadcare is not a singleton. You should store a strong
reference (as an instance variable, for example) to your Uploadcare object or
it will get deallocated.

## Using Upload API

Check the [Upload API documentation](https://github.com/uploadcare/uploadcare-swift/tree/master/Documentation/Upload%20API.md) to see all available
methods.

Each method has an implementation with a `Result` completion handler and has
an alternative `async` implementation to use with Swift concurrency.

Example of uploads:

```swift
guard let url = URL(string: "https://examples.ucarecd.net/f70b3810-1f72-4ad3-97c9-fd1c9c24db6f/-/preview/440x440/-/quality/lighter/") else { return }
guard let data = try? Data(contentsOf: url) else { return }

// You can create an UploadedFile object to operate with it
var fileForUploading1 = uploadcare.file(fromData: data)
fileForUploading1.metadata = ["myKey": "myValue"]
let uploadedFile: UploadedFile = try await fileForUploading1.upload(withName: "random_file_name.jpg", store: .store)
print(uploadedFile)

// The same method with a completion callback that returns a task that can be paused or cancelled

var fileForUploading2 = uploadcare.file(withContentsOf: url)!
let file = try await uploadcare.uploadFile(data, withName: "random_file_name.jpg", store: .auto) { progress in
    print("upload progress: \(progress * 100)%")
}

// Same method with a completion callback that returns a task that can be paused or cancelled:
let task = uploadcare.uploadFile(data, withName: "random_file_name.jpg", store: .store, metadata: ["someKey": "someMetaValue"]) { progress in
    print("upload progress: \(progress * 100)%")
} _: { result in
    switch result {
    case .failure(let error):
        print(error.detail)
    case .success(let file):
        print(file)
    }
}

// Cancel uploading if needed
task.cancel()

// task will conform to UploadTaskable if file size is less than 10 MB, and UploadTaskResumable if file size is >= 10 MB (multipart threshold)
// You can pause or resume uploading of file with size >= 10 MB if needed
(task as? UploadTaskResumable)?.pause()
(task as? UploadTaskResumable)?.resume()
```

It is possible to perform uploads in the background.
But implementation is platform-specific.
This lib doesn't provide a default implementation.
You can find an example for the iOS in our Demo app.
See [FilesListStore.swift](https://github.com/uploadcare/uploadcare-swift/blob/1e6341edcdcb887589a4e798b746c525c9023b4e/Demo/Demo/Modules/FilesListStore.swift).

## Using REST API

Refer to the [REST API documentation](https://github.com/uploadcare/uploadcare-swift/tree/master/Documentation/REST%20API.md) for all methods.

Each method has an implementation with a `Result` completion handler
and has an alternative `async` implementation to use with Swift concurrency.

Example of getting list of files:

```swift
// Make a list of files object
lazy var filesList = uploadcare.listOfFiles()

func someFilesListMethod() async throws {
    // Make a query object
    let query = PaginationQuery()
        .stored(true)
        .ordering(.dateTimeUploadedDESC)
        .limit(5)

    // Get file list
    let list = try await filesList.get(withQuery: query)
    print(list)

    // Same method with a completion callback
    filesList.get(withQuery: query) { result in
        switch result {
        case .failure(let error):
            print(error)
        case .success(let list):
            print(list)
        }
    }
}
```

Get next page:

```swift
// Check if the next page is available
guard filesList.next != nil else { return }

// Async:
let next = try await filesList.nextPage()

// With a completion callback:
filesList.nextPage { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}
```

Get previous page:

```swift
// Check if the previous page is available
guard filesList.previous != nil else { return }

// Async:
let previous = try await filesList.previousPage()

// With a completion callback:
filesList.previousPage { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}
```

## Full documentation

Read the full documentation on [GitHub](https://github.com/uploadcare/uploadcare-swift/tree/master/Documentation).

## Demo app

Check the [demo app](https://github.com/uploadcare/uploadcare-swift/tree/master/Demo) for usage examples:

* List of files
* List of groups
* File info
* File upload (both direct and multipart, including upload in background)
* Multiple file upload
* Pause and continue multipart uploading
* Project info

## Related guides

* Integration with [Android](/docs/integrations/android/)