Rest V2 vs v1 changes

Global changes

  • Basic authentication is no longer supported, only the OAuth 2.0 tokens are allowed

  • Base URL has changed from mediahaven-rest-api/ to mediahaven-rest-api/v2

  • application/json is now the default output of the API

  • MediaObjectId is renamed to RecordId (MediaObjectId is still available in API)

  • All record/media endpoints now support RecordId

  • All paged results now follow the same format

    "NrOfResults" : 25 "TotalNrOfResults": 34, "StartIndex": 0, "Results": [ { ... } ]

Media /records endpoint

  • /media endpoint has changed to /records

  • Metadata-only records can now be created by sending the metadata as body (XML and JSON is supported)



Uploaded files are now handled differently and do not follow the same flow as REST v1. Instead they are processed via a workflow process. A property workflow is available to start the correct process The default flow for MediaHaven 2.0 is media_upload.

For customers that wish to use the old flow, the workflow property needs to be set to Ingest-1.0. This is needed for customers that have custom plugins in the pretranscoder.

Fragments 21.3

Fragments no longer have a dedicated endpoint for creation. Instead they can be created via the records-endpoint.

Fragments documentation


Legacy publish 21.3

In rest V1 you could publish a record via media/:id/publish. This endpoint has been replaced with the property publish on the update endpoint.

Refer to for more information.

Specific fields BREAKING

In rest V1 it’s possible to update fields of a record via the media/:id/<field> endpoint. This endpoint is no longer available. As an alternative you can update the record by sending a POST-request to update the record with a partial sidecar.



POST<id> { "Metadata": { "Descriptive": { "Title": "My new title" } } }

Fragments and children

Rest V1 provided endpoints to request fragments of a video/audio record and children of an ensemble. They are no longer available but can still be requested via the search-api.


Rest v1

Rest v2 (search request)


Rest v1

Rest v2 (search request)




Ensemble (set)



Ensemble (collection)



Ensemble (newspaper)



Supported formats


Rest v1

Rest v2




Rest v1

Rest v2




application/xml (old style)

not supported







Dublin core

not supported



not supported


Parent/child relations and inheritance 21.1

Parent/child via the relations attribute is deprecated and replaced with adoption. During adoption inheritance of values from the parent record is now possible.

Record Type & Status

Records can now have a type & status. Supported type and status is dependent on installation and configuration.

For legacy Mediahaven records, the following applies:

  • The record type is ‘Record’

  • The status is ‘New’ if located in an ingest space, or ‘Published’ if published.

Concurrent update of records 21.1

Updating the same record at the same time by 2 users will now throw a 409 Conflict error.


When executing a search the query sent is now strictly validated. Unknown fields, non-indexed fields or corrupt query syntax will throw a 400 bad request error.


Number of records per page is now limited to 100.

Count endpoint

It’s now possible to get a count by sending a HEAD-request instead of GET-request → More info


The export API is rewritten but still supports the same features → Export request


Current user BREAKING

The current user endpoint no longer returns all the properties of the user. Relations of the user are now sub endpoints of the current user endpoint

New features


For metadata-only records it’s now possible to create versions of records. Each version starts with the status DRAFT. This object is not visible in the default search. To make it visible you will have to ACCEPT the draft or in case you don’t want to accept the DRAFT you can REJECT it. The current active version will have the status HEAD. Older version will have the status TAIL.


Profiles can now be created and modified → documentation. Note that these profiles are not the same as the profiles in the old Content Uploader. These new profiles are available in MediaHaven 2.0.

Zip tree

Zip tree is a new combination mode for the export API that exports the record with all its children


A batch API was added to support updating a large amount of records with a single request. These batches are processed asynchronously.

Events 21.1

Record events can now be requested via the API

Difference between records 21.1

An API was added to view the difference between 2 records

Improved categories/ thesaurus 21.3

Categories are replaced with the new and improved thesaurus which is integrated in the search-engine so search queries are automatically enhanced with related terms.

Generating previews on demand 21.2

It’s now possible to (re)generate the preview of a file on demand