S3 Controller

The S3 Controller handles all operations related to securely uploading files to AWS S3 storage within the AdmiralCloud platform.

This controller provides a streamlined workflow for file uploads, handling the creation of necessary resources (mediacontainers, metadata, and media entries) and managing AWS S3 temporary credentials automatically.

Reference

S3.createUpload

Use this function to initialize a new upload and retrieve temporary access credentials for AWS S3.

This function creates mediacontainers, metadata and media entries and returns instructions how to upload to S3. Use this function instead of manually creating mediacontainer, media entries and metadata.

Note: The jobId is only required when waitForCompletion is set to false or when uploading more than 10 files. Use the jobId to check if the process is completed and then use the Activity.jobResult to retrieve the instructions for the upload.

POST/v5/s3/createUpload

Request Parameters

Field	Type	Required	Description
additionalSettings	object	✗	Advanced configuration options for fine-tuning the upload process and media handling
└ contactId	integer	✗	ID of the contact to associate with this specific upload
└ isAdditionalDocument	boolean	✗	Indicates if this is a supplementary document to an existing media container
└ mediaContainerId	integer	✗	TBA
└ subtitleLanguage	iso-639	✗	ISO language code for subtitle files (e.g., "en", "de", "fr")
└ published	boolean	✗	TBA
└ ignoreMetadata	object	✗	Controls which metadata fields should be ignored during processing
└ container_name	boolean	✗	Ignore the container name metadata
└ container_description	boolean	✗	Ignore the container description metadata
└ keywordsAsTags	boolean	✗	Disable automatic conversion of keywords to tags
└ all	boolean	✗	Ignore all metadata fields
└ originalFileExtension	fileExtension	✗	Override the detected file extension
└ disableAutoGenerate	boolean	✗	When true, prevents automatic generation of derived formats
└ replacement	object	✗	Configuration for replacing an existing file
└ id	integer	✗	ID of the media item to replace
└ skipVersion	boolean	✗	When true, does not increment the version number
└ tags	array	✗	Tags to apply (test mode only)
└ metadata	array	✗	Custom metadata to apply (test mode only)
contacts	array	✗	Array of contact IDs to associate with the upload
controlGroupIds	array	✗	Array of access control group IDs to manage permissions
controlGroups	array	✗	Array of access control group IDs (deprecated) Please use controlGroupIds instead
dryRun	boolean	✗	When true, returns mock credentials for testing without affecting production data
flag	integer	✗	Flag value for the mediacontainer (0=normal, 2=hidden, 9=deleted) ≡ allowed values: 029
payload	array	✓	Array of file details to be uploaded
└ type	string	✓	Media type of the file ≡ allowed values: imagevideoaudiodocument
└ fileName	string	✓	Name of the file including file extension
└ fileSize	long	✓	Size of the file in bytes ⟨⟩ range: 1 to 5497558138880
└ originalFileExtension	string	✓	Extension of the original file (without dot, e.g. "mp4")
└ uploader	string	✗	Name or identifier of the user/system uploading the file
└ checksum	string	✗	File checksum for verification purposes
└ identifier	string	✗	Client-generated UUID to track the file throughout the upload process
└ disableAutoGenerate	boolean	✗	When set to true, automatic generation of formats and embed links is disabled
└ metadata	array	✗	Custom metadata to associate with the file
tags	array	✗	Array of tags to assign to the uploaded files
└ tagId	integer	✓	ID of the tag to apply to the file
└ flag	integer	✓	Flag value for the tag. Standard value is 0. ≡ allowed values: 0120
└ settings	object	✗	Additional settings for the tag
└ origin	string	✗	Source of the tag (e.g., "migration" for imported tags) ≡ allowed values: migration
uploadId	string	✗	Unique identifier for the upload batch session
uploadProfileId	integer	✗	ID of upload profile configuration to use Experimental
useCloudfront	boolean	✗	Set to true to use CloudFront for the upload process
waitForCompletion	boolean	✗	When true, response is returned only after upload initialization is complete. Limited to batches with less than 10 items.

// Request

{
  "payload": [
    {
      "fileName": "product_demo.mp4",
      "fileSize": 15482657,
      "type": "video",
      "originalFileExtension": "mp4",
      "uploader": "alice.developer@example.com",
      "identifier": "file-c7e2a4b1-d390-45f2-8e1c-a8b6f912d45e"
    }
  ],
  "tags": [
    {
      "tagId": 5432,
      "flag": 0
    }
  ],
  "waitForCompletion": true
}

S3.success

Make this call every time a media item has been completely uploaded to the given location.

This call also creates event for “createDownloadlink” if the upload originates from a dropsite and the dropsite is set to automatically create downloadlinks.

POST/v5/s3/success

Request Parameters

Field	Type	Required	Description
bucket	string	✓	S3 bucket name where the file was uploaded
key	string	✓	S3 object key path of the successfully uploaded file. Triggers file processing pipeline.
probe	boolean	✗	When false, skips automatic file probing after upload (testing purposes only)

Response

Field	Type	Description
jobId	string	Unique identifier for tracking the file processing job
message	string	Status message indicating current processing activity ≡ allowed values: importingSubtitlesimportingTags

S3.uploadComplete

Make this call once after all media items from this batch are uploaded. Please note: If this is an upload from a Dropsite, the session will be invalidated after this call!

POST/v5/s3/uploadComplete

Request Parameters

Field	Type	Required	Description
uploadId	string	✓	Unique identifier for the upload batch session

S3.getUploadCredentials

Use this function to retrieve upload credentials for a specific media id. Use it for example if you have a batch upload and your credentials are timing out.

NOTE: This only works until S3.success is called.

If you want to start a fresh upload, please use createUpload function. See Uploading to AdmiralCloud for more information.

GET/v6/s3/getUploadCredentials

Request Parameters

Field	Type	Required	Description
dryRun	boolean	✗	When true, returns mock credentials for testing without affecting production data
duration	integer	✗	Validity duration for the credentials in seconds (900-3600) ⟨⟩ range: 900 to 3600
mediaId	integer	✓	ID of the media item to refresh upload credentials for
s3Key	string	✓	S3 object key path for the media item to refresh credentials for

Response

Field	Type	Description
AccessKeyId	string	AWS access key ID for authenticating with S3
Expiration	date	Date and time when the temporary credentials will expire
SecretAccessKey	string	AWS secret access key for authenticating with S3
SessionToken	string	AWS session token for temporary credentials authentication
credentials	object	AWS S3 temporary credentials for file upload
└ AccessKeyId	string	AWS access key ID for S3 authentication
└ SecretAccessKey	string	AWS secret access key for S3 authentication
└ SessionToken	string	AWS session token for temporary credentials
└ Expiration	datetime	ISO 8601 formatted timestamp when credentials will expire
dryRun	boolean	When true, returns mock credentials for testing without affecting production data

API

Reference

S3.createUpload

S3.success

S3.uploadComplete

S3.getUploadCredentials

Related Articles