REST API

Initialization
List of files
File info
File metadata
Store files
Delete files
Copy file to local storage
Copy file to remote storage
List of groups
Group info
Delete group
Project info
Secure delivery
List of webhooks
Create webhook
Update webhook
Delete webhook
Document info
Convert document
Document conversion job status
Convert video
Video conversion job status
AWS Rekognition
ClamAV
Remove.bg

Initialization

Create an Uploadcare project in the dashboard and copy its API keys from there.

REST API requires both public and secret keys:

final class MyClass {
    private var uploadcare: Uploadcare
    
    init() {
        self.uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")
    }
}

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

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", secretKey: "YOUR_SECRET_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.

List of files (API Reference)

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

// Make a query object
let query = PaginationQuery()
    .stored(true)
    .ordering(.dateTimeUploadedDESC)
    .limit(5)

// Get a list of files (async):
let list = try await filesList.get(withQuery: query)

// Get a list of files (with 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:

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

// Get the next page (async):
let next = try await filesList.nextPage()

// Get the next page (with completion callback):
filesList.nextPage { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}

Get previous page:

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

// Get the previous page (async):
let previous = try await filesList.previousPage()

// Get the previous page (with completion callback):
filesList.previousPage { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}

File info (API Reference)

// Async:
let file = try await uploadcare.fileInfo(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2")

// With a completion callback:
uploadcare.fileInfo(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let file):
        print(file)
    }
}

Using query:

let fileInfoQuery = FileInfoQuery().include(.appdata)

// Async:
let file = try await uploadcare.fileInfo(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2", withQuery: fileInfoQuery)

// With a completion callback:
uploadcare.fileInfo(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2", withQuery: fileInfoQuery) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let file):
        print(file)
    }
}

File metadata (API Reference)

Get the file’s metadata:

// Async:
let metadata = try await uploadcare.fileMetadata(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2")

// With a completion callback:
uploadcare.fileMetadata(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let metadataDictionary):
        print(metadataDictionary)
    }
}

Get the metadata key's value:

// Async:
let value = try await uploadcare.fileMetadataValue(
    forKey: "myMeta",
	withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2"
)

// With a completion callback:
uploadcare.fileMetadataValue(forKey: "myMeta", withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let value):
        print(value)
    }
}

Update the metadata key's value. If the key does not exist, it will be created:

// Async:
let val = try await uploadcare.updateFileMetadata(
    withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2", 
    key: "myMeta", 
    value: "myValue"
)

// With a completion callback:
uploadcare.updateFileMetadata(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2", key: "myMeta", value: "myValue") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let value):
        print(value)
    }
}

Delete metadata key:

// Async:
try await uploadcare.deleteFileMetadata(
    forKey: "myMeta", 
    withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2"
)

// With a completion callback:
uploadcare.deleteFileMetadata(forKey: "myMeta", withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2") { error in
    if let error = error { 
        print(error)
    }
}

Store files (API Reference)

Store an individual file:

// Async:
let file = try await uploadcare.storeFile(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2")

// With a completion callback:
uploadcare.storeFile(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let file):
        print(file)
    }
}

Batch file storing:

let uuids = ["b7a301d1-1bd0-473d-8d32-708dd55addc0", "1bac376c-aa7e-4356-861b-dd2657b5bfd2"]

// Async:
let response = try await uploadcare.storeFiles(withUUIDs: uuids)

// With a completion callback:
uploadcare.storeFiles(withUUIDs: uuids) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response)
    }
}

Delete files (API Reference)

Delete an individual file:

// Async:
let file = try await uploadcare.deleteFile(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2")

// With a completion callback:
uploadcare.deleteFile(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let file):
        print(file)
    }
}

Batch file delete:

let uuids = ["b7a301d1-1bd0-473d-8d32-708dd55addc0", "1bac376c-aa7e-4356-861b-dd2657b5bfd2"]

// Async:
try await uploadcare.deleteFiles(withUUIDs: uuids)

// With a completion callback:
uploadcare.deleteFiles(withUUIDs: uuids) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response)
    }
}

Copy file to local storage (API Reference)

// Async:
let response = try await uploadcare.copyFileToLocalStorage(source: "6ca619a8-70a7-4777-8de1-7d07739ebbd9")

// With a completion callback:
uploadcare.copyFileToLocalStorage(source: "6ca619a8-70a7-4777-8de1-7d07739ebbd9") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response)
    }
}

Copy file to remote storage (API Reference)

let source = "99c48392-46ab-4877-a6e1-e2557b011176"

// Async:
let response = try await uploadcare.copyFileToRemoteStorage(source: source, target: "one_more_project", pattern: .uuid)

// With a completion callback:
uploadcare.copyFileToRemoteStorage(source: source, target: "one_more_project", makePublic: true, pattern: .uuid) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response)
    }
}

List of groups (API Reference)

let query = GroupsListQuery()
    .limit(100)
    .ordering(.datetimeCreatedDESC)
    
// Async:
let list = try await uploadcare.listOfGroups(withQuery: query)

// With a completion callback:
uploadcare.listOfGroups(withQuery: query) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}


// Using a GroupsList object
let groupsList = uploadcare.listOfGroups()

// Async:
let list = try await groupsList.get(withQuery: query)

// With a completion callback:
groupsList.get(withQuery: query) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}

Get the next page:

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

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

Get the previous page:

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

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

Group info (API Reference)

// Async:
let group = try await uploadcare.groupInfo(withUUID: "c5bec8c7-d4b6-4921-9e55-6edb027546bc~1")

// With a completion callback:
uploadcare.groupInfo(withUUID: "c5bec8c7-d4b6-4921-9e55-6edb027546bc~1") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let group):
        print(group)
    }
}

Delete group (API Reference)

// Async:
try await uploadcare.deleteGroup(withUUID: "groupId")

// With a completion callback:
uploadcare.deleteGroup(withUUID: "groupId") { error in
    if let error = error {
        print(error)
    }
}

Project info (API Reference)

// Async:
let project = try await uploadcare.getProjectInfo()

// With a completion callback:
uploadcare.getProjectInfo { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let project):
        print(project)
    }
}

Secure delivery (API Reference)

This method allows you to get an authenticated URL from your backend by using a redirect. To answer a request to that URL, your backend should generate an authenticated URL to your file and perform REDIRECT to a generated URL. A redirected URL will be caught and returned in the completion handler of that method.

Example: https://yourdomain.com/{UUID}/ — backend redirects to https://cdn.yourdomain.com/{uuid}/?token={token}&expire={timestamp}.

let url = URL(string: "https://yourdomain.com/FILE_UUID/")!

// Async:
let value = try await uploadcare.getAuthenticatedUrlFromUrl(url)

// With a completion callback:
uploadcare.getAuthenticatedUrlFromUrl(url) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let value):
        // Value is https://cdn.yourdomain.com/{uuid}/?token={token}&expire={timestamp}
        print(value)
    }
}

List of webhooks (API Reference)

// Async:
let webhooks = try await uploadcare.getListOfWebhooks()

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

Create webhook (API Reference)

Create and subscribe to a webhook. You can use webhooks to receive notifications about your uploads. For instance, once a file gets uploaded to your project, we can notify you by sending a message to a target URL.

let url = URL(string: "https://yourwebhook.com")!

// Async:
let webhook = try await uploadcare.createWebhook(targetUrl: url,  event: .fileUploaded, isActive: true, signingSecret: "someSigningSecret")

// With a completion callback:
uploadcare.createWebhook(targetUrl: url,  event: .fileUploaded, isActive: true, signingSecret: "someSigningSecret") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let webhook):
        print(webhook)
    }
}

Update webhook (API Reference)

Update webhook attributes.

let url = URL(string: "https://yourwebhook.com")!
let webhookId = 100

// Async:
let webhook = try await uploadcare.updateWebhook(id: webhookId, targetUrl: url, event: .fileInfoUpdated, isActive: false, signingSecret: "someNewSigningSecret")

// With a completion callback:
uploadcare.updateWebhook(id: webhookId, targetUrl: url, event: .fileInfoUpdated, isActive: true, signingSecret: "someNewSigningSecret") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let webhook):
        print(webhook)
    }
}

Delete webhook (API Reference)

Unsubscribe and delete a webhook.

let url = URL(string: "https://yourwebhook.com")!

// Async:
try await uploadcare.deleteWebhook(forTargetUrl: url)

// With a completion callback:
uploadcare.deleteWebhook(forTargetUrl: url) { error in
    if let error = error {
        print(error)
    }				
}

Document info (API Reference)

The method allows you to determine the document format and possible conversion formats:

// Async:
let documentInfo = try await uploadcare.documentInfo("fileUUID")

// With a completion callback:
uploadcare.documentInfo("fileUUID") { result in
    switch result {
        case .failure(let error):
            print(error)
        case .success(let documentInfo):
            print(documentInfo)
    }
}

Convert document (API Reference)

You can convert multiple files with one request:

let task1 = DocumentConversionJobSettings(forFile: file1)
    .format(.odt)
let task2 = DocumentConversionJobSettings(forFile: file2)
    .format(.pdf)
    
// Async:
let response = try await uploadcare.convertDocumentsWithSettings([task1, task2])

// With a completion callback:
uploadcare.convertDocumentsWithSettings([task1, task2]) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response)
    }
}

Alternatively, you can pass custom "paths" param as an array of strings (see (documentation)):

// Async:
let response = try await uploadcare.convertDocuments([":uuid/document/-/format/:target-format/"])

// With a completion callback:
uploadcare.convertDocuments([":uuid/document/-/format/:target-format/"]) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response)
    }  
}

Document conversion job status (API Reference)

// Async
let job = try await uploadcare.documentConversionJobStatus(token: 123456)

switch job.status {
case .failed(let conversionError):
	print(conversionError)
default: 
	break
}

// With a completion callback:
uploadcare.documentConversionJobStatus(token: 123456) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let job):
        switch job.status {
        case .failed(let conversionError):
            print(conversionError)
        default: 
            break
        }
    }
}

Convert video (API Reference)

You can convert multiple video files with one request:

let task1 = VideoConversionJobSettings(forFile: file1)
    .format(.webm)
    .size(VideoSize(width: 640, height: 480))
    .resizeMode(.addPadding)
    .quality(.lightest)
    .cut( VideoCut(startTime: "0:0:5.000", length: "15") )
    .thumbs(15)
    
let task2 = VideoConversionJobSettings(forFile: file2)
    .format(.mp4)
    .quality(.lightest)
    
// Async:
let response = try await uploadcare.convertVideosWithSettings([task1, task2])

// With a completion callback:
uploadcare.convertVideosWithSettings([task1, task2]) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response)
    }   
}

Alternatively, you can pass custom "paths" param as an array of strings (see (documentation)):

// Async:
let response = try await uploadcare.convertVideos([":uuid/video/-/format/ogg/"])

// With a completion callback:
uploadcare.convertVideos([":uuid/video/-/format/ogg/"]) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response)
    }   
}

Video conversion job status (API Reference)

// Async:
let job = try await uploadcare.videoConversionJobStatus(token: 123456)

switch job.status {
case .failed(let conversionError):
    print(conversionError)
default: 
    break
}

// With a completion callback:
uploadcare.videoConversionJobStatus(token: 123456) { result in    
    switch result {
    case .failure(let error):
        print(error)
    case .success(let job):
        print(job)
        switch job.status {
        case .failed(let conversionError):
            print(conversionError)
        default: 
            break
        }
    }
}

Add-Ons

An Add-On is an application implemented by Uploadcare that accepts uploaded files as input and can produce other files and/or appdata as output.

AWS Rekognition (API Reference)

Execute AWS Rekognition Add-On for a given target to detect labels in an image. Note: Detected labels are stored in the file's appdata.

// Async:
let response = try await uploadcare.executeAWSRekognition(fileUUID: "uuid")

// With a completion callback:
uploadcare.executeAWSRekognition(fileUUID: "uuid") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response) // contains requestID
    }
}

Check status:

// Async:
let status = try await uploadcare.checkAWSRekognitionStatus(requestID: response.requestID)

// With a completion callback:
uploadcare.checkAWSRekognitionStatus(requestID: "requestID") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let status):
        print(status)
    }
}

Execute and wait for completion:

let status = try await uploadcare.performAWSRekognition(fileUUID: "uuid")
print(status)

AWS Rekognition Moderation (API Reference)

Execute AWS Rekognition Moderation Add-On for a given target to detect moderation labels in an image. Note: Detected moderation labels are stored in the file's appdata.

// Async:
let response = try await uploadcare.executeAWSRekognitionModeration(fileUUID: "uuid")

// With a completion callback:
uploadcare.executeAWSRekognitionModeration(fileUUID: "uuid") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response) // contains requestID
    }
}

Check status:

// Async:
let status = try await uploadcare.checkAWSRekognitionModerationStatus(requestID: response.requestID)

// With a completion callback:
uploadcare.checkAWSRekognitionModerationStatus(requestID: "requestID") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let status):
        print(status)
    }
}

Execute and wait for completion:

let status = try await uploadcare.performAWSRekognitionModeration(fileUUID: "uuid")
print(status)

ClamAV (API Reference)

Execute ClamAV virus checking Add-On for a given target.

let parameters = ClamAVAddonExecutionParams(purgeInfected: true)

// Async:
let response = try await uploadcare.executeClamav(fileUUID: "uuid", parameters: parameters)

// With a completion callback:
uploadcare.executeClamav(fileUUID: "uuid", parameters: parameters) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response) // contains requestID
    }
}

Check status:

// Async:
let status = try await uploadcare.checkClamAVStatus(requestID: response.requestID)

// With a completion callback:
uploadcare.checkClamAVStatus(requestID: "requestID") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let status):
        print(status)
    }
}

Execute and wait for completion:

let parameters = ClamAVAddonExecutionParams(purgeInfected: true)
let status = try await uploadcare.performClamav(
    fileUUID: "fileUUID",
	parameters: parameters
)
print(status)

Remove.bg (API Reference)

Execute remove.bg background image removal Add-On for a given target.

// more parameters in RemoveBGAddonExecutionParams model
let parameters = RemoveBGAddonExecutionParams(crop: true, typeLevel: .two)

// Async:
let response = try await uploadcare.executeRemoveBG(fileUUID: "uuid", parameters: parameters)

// With a completion callback: 
uploadcare.executeRemoveBG(fileUUID: "uuid", parameters: parameters) { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let response):
        print(response) // contains requestID
    }
}

Check status:

// Async:
let status = try await uploadcare.checkRemoveBGStatus(requestID: response.requestID)

// With a completion callback: 
uploadcare.checkRemoveBGStatus(requestID: "requestID") { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let status):
        print(status)
    }
}

Execute and wait for completion:

// more parameters in RemoveBGAddonExecutionParams model
let parameters = RemoveBGAddonExecutionParams(crop: true, typeLevel: .two)

let status = try await uploadcare.performRemoveBG(fileUUID: "uuid", parameters: parameters)
print(status)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

REST API.md

REST API.md

REST API

Initialization

List of files (API Reference)

File info (API Reference)

File metadata (API Reference)

Store files (API Reference)

Delete files (API Reference)

Copy file to local storage (API Reference)

Copy file to remote storage (API Reference)

List of groups (API Reference)

Group info (API Reference)

Delete group (API Reference)

Project info (API Reference)

Secure delivery (API Reference)

List of webhooks (API Reference)

Create webhook (API Reference)

Update webhook (API Reference)

Delete webhook (API Reference)

Document info (API Reference)

Convert document (API Reference)

Document conversion job status (API Reference)

Convert video (API Reference)

Video conversion job status (API Reference)

Add-Ons

AWS Rekognition (API Reference)

AWS Rekognition Moderation (API Reference)

ClamAV (API Reference)

Remove.bg (API Reference)

Files

REST API.md

Latest commit

History

REST API.md

File metadata and controls

REST API

Initialization

List of files (API Reference)

File info (API Reference)

File metadata (API Reference)

Store files (API Reference)

Delete files (API Reference)

Copy file to local storage (API Reference)

Copy file to remote storage (API Reference)

List of groups (API Reference)

Group info (API Reference)

Delete group (API Reference)

Project info (API Reference)

Secure delivery (API Reference)

List of webhooks (API Reference)

Create webhook (API Reference)

Update webhook (API Reference)

Delete webhook (API Reference)

Document info (API Reference)

Convert document (API Reference)

Document conversion job status (API Reference)

Convert video (API Reference)

Video conversion job status (API Reference)

Add-Ons

AWS Rekognition (API Reference)

AWS Rekognition Moderation (API Reference)

ClamAV (API Reference)

Remove.bg (API Reference)