Basic API Structure

Resources

• Authorization
  The oauth resource permits to obtain an OAuth 2.0 API access token from given application credentials (client_id / client_secret). An OAuth token is necessary to authorize API requests to most other resources. The needed application credentials are created from the MediaHub UI.
  
  
• Backtraces
  Permits to trace copies of AutoGraph watermark-protected videos back to the autograph_tag associated with the video copy. Allows to track video copies to the original downloader of a file or the original viewer of a video stream/playlist.

• Users
  Keeps information about your user and user account. Can be used to query all data stored in your user profile or to update your account information programmatically,
  
  
• Pipelines
  Defines the Input/Output Directives that should be used for downloading/uploading the input files and converted output files as well as the access credentials necessary for it. Also allows to set the queue type (currently "default" is the only choice as we have just one type of queue), the notification scheme (ping_urls) and a few other options for how to store/upload the output files. 
  
  
• Codecs
  Defines audio / video encoders with their limitations or specific properties. All properties relevant for standards compliance and interoperability are captured within the codecs object. This includes exposing the allowed "profile" choices available with a codec as well as all properties that effect the codec's "level", e.g. max_width, max_height, max_bitrate, max_buffer_size, max_framerate or max_nb_ref frame (= H.264-specific).
  
  
• Presets
  A combination of audio codec (plus its max. limits as capabilities) + video codec (plus its max. limits as capabilities) and container format and video/audio settings (resizing, cropping, resampling, etc.) and thumbnail settings as well as logo settings. So Presets is a reusable preset for video conversion.
  
  
• Playlists
  Allows to obtain HLS or MPEG DASH playlists for video files/jobs encoded in MP4 format. Permits streaming the respective videos in HLS/DASH compatible video players.

• Jobs
  A Job is defined by its Input file (and potentially also further manual overrides to some input file properties), a (list of) Outputs each having a Preset reference, output filename and a few optional conversion settings (e.g. video/audio settings overrides, enabling/disabling thumbnail creation, enabling/disabling logo placement, enabling/disabling AutoGraph forensic watermark protection, etc.).
  
  
• Files
  The Files resource permits looking up meta-information for input and output files that got uploaded to our storage or processed/created from running a video conversion Job. Jobs will create a new item in the Files resource for each output file produced by a Job automatically and also add additional meta-data to previously uploaded input files, if available. Access to the actual file's content (= binary data) is possible via the /files/downloads/ endpoint from where then an actual download link for the file can be obtained. 
  
  
• Statistics
  The statistics resource permits to obtain various usage statistics (bandwidth, storage, encoding) either for the entire user account as a whole, or also separately for each application that exists in the account.

Input/output files to be used in Jobs and Pipelines can be internally or externally stored/hosted. The AutoGraph feature is currently only available when storing the output videos "internally", so on our MediaHub storage (that's because we actually generate the autographed video files on demand every time they are streamed or downloaded - so transmitting/storing them to external storages would be wasteful with regard to both bandwidth and storage space).

Every Pipeline has a corresponding root "folder" entry in the Files resource by default and calls to "/files/uploads" (as well as "/files/downloads") endpoints together with specifying a pipeline id as query parameter will upload (or download) files relative to the Pipeline root folder.

Upon every upload of a new input file to the internal storage, also automatically an entry in the Files resource is created for the newly uploaded object with some default meta-data (like the filename, setting the parent folder of the file, file ending, etc.). Detailed meta-information (like video/audio codec, playlength, resolution) will be populated just once the uploaded object was actually used in a conversion job.

API Responses

All APIs respond with a HTTP response status code and a JSON as response body. In case of success, the HTTP status code is 200 and contains the effective payload in JSON format. In case of an error, the HTTP status code is set to 4xx and the response body consists of an error json containing a error code, error message and (long) error description.