General info

  • UTF-8 encoding is used in every request and server response
  • Only JSON format is used in every request and response
  • Every request should be made using HTTPS
  • If an employee identifier is required, please provide e-mail or Calamari user login
  • Usage of this API is limited. You can make 10 requests/second, 720 requests/hour, 2880 requests/day. If you need more contact with us.
  • Please note that every once in a while, a new parameters can appear in JSON responses. Please include this in your client.

Authentication

Before you can use Calamari API, you have to enable "API Access" in configuration panel. Please keep generated ApiKey in secret. Every method in this API is authenticated using HTTP Basic Authentication (more info).

As username use calamari. As password use the API key generated in Calamari configuration panel.

Responses

Returned HTTP status code indicates method result. In general:

  • 2xx - Request successful.
  • 4xx - Api usage errror. Can be fixed by changing request parameters.
  • 5xx - Server error. Something wrong happened in Calamari backend. Please wait a while and repeat your request.

In particular, you should implement:

  • 200 - Request successful. More information is returned in json object. Object schema depends on method.
  • 201 - Request successful. No result returned.
  • 400 - Error occurred. Additional information provided in json response (ErrorResponse format: more info below)
  • 401 - Authentication failure. There are two possible reasons: disabled API access or invalid ApiKey provided
  • 403 - Access forbidden
  • 404 - Invalid method URL
  • 405 - HTTP method not allowed, please verify HTTP method of the request
  • 429 - Too many requests in a given amount of time. API limits are 20 requests/second, 1500 requests/hour, 10000 requests/day
  • 5xx - Something wrong happened in Calamari backend. Please wait a while and repeat your request. If error still occurs, drop us a line.

ErrorResponse format

If status 4xx is returned, you can read additional information from returned json object.

{
  "message": "string",
  "code": "string",
  "field": "string"
}
  • message - Human readable error explanation.
  • code - Error code. Possible value depends on method but there is few common error codes.
  • field - Which field of payload object caused error. NULL when error is not related to particular field

Common error codes:

  • AUTH - Authentication failure. There are two possible reasons: disabled API access or invalid ApiKey provided. Used when returned HTTP status code is 401.
  • HTTP_METHOD_NOT_ALLOWED - HTTP method not allowed, please verify HTTP method of the request. Used when returned HTTP status code is 405.
  • INVALID_METHOD_URL - HTTP method not allowed, please verify HTTP method of the request. Used when returned HTTP status code is 404.
  • QUOTA_EXCEEDED - Too many requests in a given amount of time. Used when returned HTTP status code is 429.
  • INVALID_JSON_PAYLOAD - Json object you sent cannot be interpreted by server. Please check object format and provided data due to api specification.
  • UNKNOWN_ERROR - We don't know what happened but will investigate.

Terms of use and changes policy

Responses and requests objects can be extended. If you cannot recognize a json object attribute, just ignore it. Here you can find terms of use of all Calamari services.

Previous page