Matas API Documentation

How to use the API

API requests must include be made to the Matas API base url.

Each request must include an Accept header with the value application/json.

Valid API request

As state above, the Matas API is located at

curl --header "Accept: application/json" ""

Expose the HTTP response headers

If you want to expose HTTP response headers, use the --include option:

curl --include --header "Accept: application/json" ""


All API requests of the Matas API require authentication.

To authenticate yourself with the Matas API, you'll have to create a valid personal access token from the Matas Extranet. When making requests, the token must be included in the Authorization header as a Bearer token.

curl --header "Accept: application/json" --header "Authorization: Bearer :personal_access_token:" ""

If authentication information is not valid or is missing, the Matas API returns an error message with a status code of 401:

{ "message":"Unauthenticated." }

Status codes

The API is designed to return different status codes according to context and action. This way, if a request results in an error, you can get insight into what went wrong.

The following table gives an overview of how the API functions generally behave.

Request type Description
GET Access one or more resources and return the result as JSON.
POST Return 201 Created if the resource is successfully created and return the newly created resource as JSON.
PUT Return 200 OK if the resource is modified successfully. The (modified) result is returned as JSON.
DELETE Returns 204 No Content if the resource was deleted successfully.

The following table shows the possible return codes for API requests.

Return values Description
200 OK The GET, PUT or DELETE request was successful, and the resource(s) itself is returned as JSON.
204 No Content The server has successfully fulfilled the request, and there is no additional content to send in the response payload body.
201 Created The POST request was successful, and the resource is returned as JSON.
401 Unauthorized The user isn’t authenticated. A valid personal access token is necessary.
403 Forbidden The request isn’t allowed. For example, the user isn’t allowed to delete a project.
404 Not Found A resource couldn’t be accessed. For example, an ID for a resource couldn’t be found.
405 Method Not Allowed The request isn’t supported.
422 Unprocessable Entity The entity couldn’t be processed. For example, a required parameter for a new resource was omitted.
500 Server Error While handling the request, something went wrong on the server.


The Matas API supports offset-based pagination. Almost all endpoints that return multiple results will be paginated.

Offset-based pagination

Sometimes, the returned result spans many pages. When listing resources, you can pass the following parameters:

Parameter Description
page Page number (default: 1).
per_page Number of items to list per page (default: 15, max: 100).

In the following example, we list page 2 of all orders, while listing 30 orders per page

curl --header "Accept: application/json" --header "Authorization: Bearer :personal_access_token:" ""