# 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](https://en.wikipedia.org/wiki/Representational_state_transfer) 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                 |
| <p>first\_</p><p>result</p> | 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:

```javascript
{
  "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                                                             |
| <p>first\_</p><p>result</p> | 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\_erro&#x72;*\_*&#x69;d | An Error Id that can be communicated to your Customer Support contact to help them troubleshoot the issue |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.mediarithmics.io/resources/api-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.