Extending your server with the Media Masher API

The Media Masher API is a RESTful interface that allows you to programmatically manage your media and resources, as well as trigger encode, decode, and transcode jobs. This guide shows you how to set up your server to utilize the Media Masher API.

Authentication

Create API Key

The server requires an API key to authenticate requests. This key must be generated on masher.media and added to your server’s environment variables or configuration file.

If you’ve used Media Masher before, you may already have an API key. If not, you can create one by following these steps:

1. Log in to masher.media.
2. Click on the user button in the top right corner of the page.
3. Select Security from the dropdown menu.
4. Click on the API Keys link in the left navigation.
5. Enter a name for your API key so you can identify it later.
6. Optionally,
   1. Set an expiration date for the key.
   2. Restrict the permissions of the key.
   3. Choose a hashing algorithm for the key.
7. Click Generate Key to create a new API key.

Requests

To authenticate your requests, include the API key in the Authorization header (it should NOT be prefixed with Bearer). For example, the following code will retrieve your most recently updated mash:

// best to retrieve key from environment or configuration
const key = 'your-api-key'
const endpoint = 'https://api.masher.media/media-mash'
const headers = { 
  'Authorization': key, 'Content-Type': 'application/json' 
}
const body = JSON.stringify({ byProperty: 'updated_at' })
const request = { method: 'POST', headers, body }
const response = await fetch(endpoint, request)
const { data, error } = await response.json()

Responses

If the request is handled successfully, the API will return a 200 status code along with an object in JSON format having a data property that contains the actual response. If errors arise a 200 code may still be returned, but the object will contain an error property that contains an error object having a message property describing the issue.

Endpoints

The Media Masher API offers endpoints to manage and manipulate media and resources, organized by functionality such as encoding, decoding, transcoding, and resource management. Each category includes actions like starting a job, checking status, and performing CRUD operations. Below is an overview of each endpoint category and their actions.

Decode

The Decode endpoints in the Media Masher API allow users to extract metadata from media files. This process involves analyzing the media file to retrieve information such as dimensions, duration, and format. The Decode category includes actions to start a decoding job and check its status.

Start

The decode start endpoint allows you to start a decoding job. The request should be a DecodeArgs object. The response will be an Identified object or a Decoding object, depending on whether the job immediately completed.

Status

The decode status endpoint allows you to check the status of a decoding job. The request should be an Identified object. The response will be an Identified object or a Decoding object, depending on whether the job is still in progress or has been completed.

Encode

The Encode endpoints in the Media Masher API allow users to convert a mash into a single output file of any type. This process involves specifying the input mash, desired output format, and any additional parameters. The Encode category includes actions to start an encoding job and check its status.

Start

The encode start endpoint allows you to start an encoding job. The request should be an EncodeArgs object. The response will be an Identified object or an Encoding object, depending on whether the job immediately completed.

Status

The encode status endpoint allows you to check the status of an encoding job. The request should be an Identified object. The response will be an Identified object or an Encoding object, depending on whether the job is still in progress or has been completed.

Transcode

The Transcode endpoints in the Media Masher API allow users to convert media files from one format to another. This process involves specifying the input media, desired output format, and any additional parameters. The Transcode category includes actions to start an encoding job and check its status.

Start

The transcode start endpoint allows you to start a transcoding job. The request should be a TranscodeArgs object. The response will be an Identified object or a Transcoding object, depending on whether the job immediately completed.

Status

The transcode status endpoint allows you to check the status of a transcoding job. The request should be an Identified object. The response will be an Identified object or a Transcoding object, depending on whether the job is still in progress or has been completed.

Resources

The Resources endpoints in the Media Masher API allow users to upload and manage resources, which include encodings, decodings, and transcodings. The Resources category includes actions to perform CRUD operations on resources.

Delete

The resources delete endpoint allows you to remove one or more resources from the server. The request should be an Identified object or an array of Identified objects. The response will be an Identified object or an array of Identified objects, depending on the request.

Insert

The resources insert endpoint allows you to add one or more resources to the server. The request should be a single StorableResource object or an array of StorableResource objects. The response will be a ResourceInsertResponse object or an array of ResourceInsertResponse objects, depending on the request.

Row

The resources row endpoint allows you to retrieve a single resource from the server. The request should be an Identified object. The response will be a StoredResource object.

Select

The resources select endpoint allows you to search for resources on the server. The request should be a ResourceSearchRequest object. The response will be a ResourceSearchResponse object.

Update

The resources update endpoint allows you to update one or more resources on the server. The request should be a single StoredResource object or an array of StoredResource objects. The response will be a StoredResource object or an array of StoredResource objects, depending on the request.

Media

The Media endpoints in the Media Masher API allow users to manage media objects, which represent a collection of resources and type specific metadata. The Media category includes actions to perform CRUD operations on media files.

Insert

The media insert endpoint allows you to add one or more media objects to the server. The request should be a single StorableMedia object or an array of StorableMedia objects. The response will be an Identified object or an array of Identified objects, depending on the request.

Select

The media select endpoint allows you to search for media on the server. The request should be a MediaSearchRequest object. The response will be a MediaSearchResponse object.

Update

The media update endpoint allows you to update one or more media objects on the server. The request should be a single StoredMedia object or an array of StoredMedia objects. The response will be an Identified object or an array of Identified objects, depending on the request.

Delete

The media delete endpoint allows you to remove one or more media objects from the server. The request should be an Identified object or an array of Identified objects. The response will be an Identified object or an array of Identified objects, depending on the request.

Row

The media row endpoint allows you to retrieve a single media object from the server. The request should be an Identified object. The response will be a StoredMedia object.

Mash

The media mash endpoint returns a single media object to be loaded into the editor. The request should be a MediaMashRequest object. The response will be a StorableMedia object.