Skip to content

Message encoding

HTTP methods

MiaRec API supports the following HTTP methods:

HTTP method Description
GET Retrieve a resource or a list of resources (users, groups, calls, and so on). Examples: https://miarec.example.com/api/v2/users.json, https://miarec.example.com/api/v2/users/e00f043e-f288-11e4-aa29-e03f497dbdff.json
POST Create a new resource, or run an action on a resource (for example, pause recording)
PUT Modify an existing resource. Only the attributes included in the request body are changed
DELETE Delete a resource

HTTP headers

  • HTTP Basic Authentication header

    Each request must contain the HTTP Basic Authentication header with a valid user name and password. The user must exist in MiaRec and have the REST API permission. See Security and authentication.

  • Accept header

    Send Accept: application/json. MiaRec API responds in JSON, except for endpoints that return binary data, such as an audio file or a logo image.

  • Content-Type header

    On PUT and POST requests with a JSON body, send Content-Type: application/json. Endpoints that accept binary data, such as the logo image upload, expect the content type of that data.

HTTP body

The body of a request or response carries data in JSON format. A request body is sent on PUT and POST. A response body is returned on GET, on PUT (the updated resource), and on POST (the URL of the created resource).

Each resource is wrapped in an object named after the resource type, both in requests and responses:

{
    "user": {
        "name": "John Smith",
        ...
    }
}

Character sets

Submitted JSON data must be encoded in UTF-8. Responses are encoded in UTF-8.

Format of date and time values

All date and time values are returned in ISO 8601 format with a time zone offset, for example 2024-06-05T01:35:55+03:00 or 2024-06-05T01:40:51.344000+03:00. It is the responsibility of the client application to convert them to the appropriate time zone before displaying them to a user.

The time zone of the values is the time zone of the API user. If the user has no time zone configured, the time zone of the user's group, tenant, or the system default is used.

Date and time values submitted to the API (for example, valid_till of a user) are accepted in ISO 8601 format as well.

Identifiers

Resources are identified by UUIDs, for example e00f043e-f288-11e4-aa29-e03f497dbdff. An ID that is not a valid UUID is answered with 404 Not Found.