API Reference
  1. Core features

Upload

Upload assets to Orange Logic

There are various upload APIs designed for different use cases. The appropriate API depends on the following factors:

Review the sections below to determine the best upload API for your use case.

Integrations, cloud file transfers, and peak performance

The cloud ingest APIs are recommended for integrations with third-party software systems and large file transfers. The only file size limitation is the cloud storage provider’s file size limit. For example, Amazon S3 has a 50TB file size limit.

Direct upload from a cloud storage bucket

You can upload a file from a Google Cloud Storage bucket to Orange Logic without passing the file through the Orange Logic web application. This method optimizes bandwidth, performance, and scalability. Additionally, you can map metadata to Orange Logic metadata fields, configure the upload to run in the background, and set the indexing priority.

To use this upload method, your Orange Logic administrator must configure the Google Cloud Storage bucket as a storage device in the Orange Logic platform. After this one-time setup step is complete, files can be transferred to Orange Logic on an ongoing basis. We recommend ensuring the cloud storage origin bucket is located within the same region as your Orange Logic server.

📙

Feature documentation

Orange Logic administrators with a Link account can go to the Storage devices article to learn more.

Direct upload from a public URL

We are expanding the direct cloud storage upload API to support additional cloud storage services. In the meantime, if your files are stored in another cloud storage service, such as Amazon S3 or Microsoft Azure, you can use the Upload media with URL AP. These files must have a public URL. This API does not require any additional setup, and there are several processing options for asynchronous uploads.

You can also use this API to upload any file with a public URL, such as a Box or Dropbox file.

Upload local files greater than 1.5GB

You can use the Multi-part upload API calls to upload local files that are larger than 1.5 GB. This method breaks large files into chunks that can be uploaded simultaneously. You’ll use a series of API calls to initiate an upload transaction, upload the chunks, and finalize the upload. After the transaction is completed, Orange Logic automatically reassembles the asset. Additionally, if any chunk fails to upload, you’ll only need to retry that chunk, not the entire upload. Throughput for this process is high but has a 1-2Gbps maximum. For optimal performance and scalability, we recommend uploading from a cloud storage bucket if possible.

Upload small local files

⚠️

Caution

These APIs do not have high throughput and can impact Orange Logic performance. Therefore, they are recommended for small file uploads only.

The following APIs are designed for occasional file uploads from a local machine. Uploads are limited to 1.5GB.

  • Upload small batches of files: Use the Upload media API to upload multiple files simultaneously. You can choose whether the upload is processed in the background or not. The entire upload size limit is 1.5GB.
  • Upload a single small file: Use the Upload new media API to upload a single file. You can add metadata to the asset during upload, and there are more granular options for asynchronous uploads.
  • Upload a new version of an existing asset: Use the Upload new version API API to upload a single file from your computer to Orange Logic as a new version of an existing asset.

Metadata mapping

By default, all upload transactions import and map metadata according to the folder’s import mapping template.

🎓

Insight: Import mapping templates

Files can have embedded metadata, such as the title, usage rights, date, and keywords. For example, a photograph’s metadata can include the title, date, country, keywords, and photographer. When you upload files, the Orange Logic platform can map the embedded metadata to the appropriate fields.

Additionally, when you upload assets, you can also upload:

  • A central metadata file: A file with various metadata for multiple assets.
  • Sidecar files: Separate files that store metadata for individual assets. For example, a photographer can add photoshoot data, like the date and location, to the camera. Then, the camera captures an image in one file and saves the metadata in a separate file. The separate sidecar file has the same name as the photo and a different file extension.

Upload processing options

Many upload APIs have granular options to process the upload synchronously. The following options are available in the importMode and UploadMode parameters. Options are listed from the longest to the shortest amount of time to complete the API call:

  • ProcessInLine: The API call is complete only when the asset is fully ingested, meaning all formats have been generated. This option takes the longest amount of time.
  • ProcessProxiesInBackground: The API call is complete after the asset is available for download in Orange Logic. Proxies and thumbnails are generated in the background.
  • ProcessProxiesAndParentAndIndexInBackground: The API call is complete after the asset is available to view and download in Orange Logic. Proxies and thumbnails are generated in the background. Indexing also occurs in the background, including processing the relationship between the uploaded asset and its container. The uploaded asset is available quickly, but it won't appear in search results until the background processes are finished.
  • ProcessFullyInBackground: The API call is complete when the asset record has been created and can receive updates with subsequent API calls. The metadata import and format generation occur in the background. Users can see the asset record, but embedded metadata might not appear until the background process has finished.
  • ProcessFullyInBackgroundLite: The API call is complete immediately after uploading the file, and all file processing occurs in the background, meaning that there is a delay before the asset record is created in Orange Logic. This option takes the shortest amount of time.
    ##Upload privileges

Users must have the Can upload files in Cortex Security Function to use the upload calls.
Additionally, users need upload permission to upload new assets or new versions of existing assets.