Using our API

mediarithmics is built on an API first model so pretty much anything that you can do in the UI or other tools can be done using our API.

API base url

The current API base url is https://api.mediarithmics.com. Please use https as support for http has been discontinued.

This may change in the future, so make it easy to change it in your integration with mediarithmics API.

API format

The mediarithmics API is a set of REST APIs. If you need a refresher, please check here for the basic principles ruling over REST APIs.

Body format

The mediarithmics API supports the JSON format, both for requests and responses. You should add the Content-Type: application/json header to each of your requests that contains a Body (PUT/POST) that will be parsed by the platform.

Response format

Each time the mediarithmics platform sends a result over an API, a Wrapper is applied.

Note: This Wrapper should not be used by your application(s) when you are sending a request to mediarithmics. Those are only used in the API responses.

Single resource wrapper

When a single resource is returned by the platform, the following wrapper is applied:

{
  "status": "ok",
  "data": {
    .....
  }
}

field	value
status	The status of the response. Value is either: ok, error
data	The resource returned by the platform

Resource list wrapper - non-paginated APIs

Note: We are currently migrating a lot of our APIs to the 'paginated' model. However, some of our oldest APIs have not yet migrated. So the following model still might apply to some APIs. If some of the API that you are using are not yet paginated, please ask to have your Customer Support contact so that he can give you a migration date.

When a non-paginated list of resources is returned, the wrapper is:

{
  "status": "ok",
  "count": 1,
  "first_result": 0,
  "max_results": 20,
  "data": [
    {
      ....
    },

    {
      ....
    }
  ]
}

field	value
status	The status of the response. Value is either: ok, error
data	The list of resources returned by the platform
count	The number of elements in the returned array of resources
first_ result	The index of the first element returned in the data array
max_results	The number of elements returned in the current page (e.g., the page size)
max_result	deprecated Equivalent to max_results

Resource list wrapper - paginated APIs

When a paginated list of resources is returned, the wrapper is:

{
  "status": "ok",
  "count": 30,
  "first_result": 20,
  "max_results": 30,
  "total": 100,
  "data": [
    {
      ....
    },
    {
      ....
    }
  ]
}

field	value
status	The status of the response. Value is either: ok, error
data	The list of resources returned by the platform
count	The number of elements in the returned array of resources
first_ result	The offset of the first element returned in the data array
max_results	The maximum number of results (limit) asked by the user for this page
total	The total number of items that are available on the platform and that can be retrieved through the 'pages' of the API
max_result	deprecated Equivalent to max_results

You can use first_result and max_results query parameters on paginated lists of resources to browse through the list.

For example, get 100 elements starting from an offset of 50:

https://api.mediarithmics.com/v1/resources?max_results=100&first_result=50

Errors

Whenever the API is returning an error, the response is formatted using:

{
  "status": "error",
  "error": "Resource Not Found",
  "mics_error_id": "fe10c406-15fc-48a5-a92f-6e9a5e921560"
}

field	value
status	The status of the response. Value is error
error	The error message generated by the platform
mics_error_id	An Error Id that can be communicated to your Customer Support contact to help them troubleshoot the issue