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

Sending documents

Authentication

Last modified 2yr ago

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