Media Resource

You can use the Media resource to view media information and add media directly to the Media Library in Surpass. 

Media Resource

Below we have listed the operations, HTTP verbs and an example URL for the Media resource within the Surpass API.
Operation HTTP Verb Example URL
Retrieve GET https://...surpass.com/api/v2/Media
Create POST https://...surpass.com/api/v2/Media/{id}

Attributes for the Media Resource

Within the table below we have provided all of the attributes included in the Media resource. This includes the attribute name, data type, the default properties returned by GET requests, and if the attribute is mandatory when sending a POST request. Remember that if an attribute is not mandatory it can be omitted from the body of the POST request.
Attribute Name Type Notes Unique Identifier Default Properties (GET) Mandatory for Create (POST) MaxLength
id int The media object's unique ID X X
name string Media name + "." + extension X X(*) 80
embedLink string The URL for embedding images in stem text X
data byte File X
subject resource ID or Ref can be supported X X

Additional Notes

  • *Media name - required.
  • *Extension - required; Supported types (extensions) are: bmp, gif, jpg, png, swf, flv, wav, mp3, mp4, mpeg, avi, wmv, mov, and pdf.
  • Data attribute must be Base64 encoded and passed as a byte string.

GET Requests

The Media resource provides the ability to search for media objects based on parameters and properties in a GET request. If you want to embed images in stem text strings via Item PUT/POST, using a Media GET request will provide you with the image’s correct embed link. Some examples are below:

Example GET response (JSON)
Example GET response (XML)

POST Request and Return

The POST Media method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.

Example POST request and response (JSON)
Example POST request and response (XML)

Depending on how the request was submitted the response will be returned in either JSON or XML format. If the call was unsuccessful then you will receive an error message, all error messages available in the Surpass API can be found here.


Required Permissions

To successfully call the POST Media method, the user specified in the header of the request must have the ‘Item Writer’, ‘Item Reviewer’ or ‘Item Publisher’ permission in Surpass.

Feedback and Knowledge Base