Here is a sample of the API response:

HTTP/1.1 200 OK
Date: Mon, 07 Sep 2015 23:02:09 GMT
Expires: Mon, 07 Sep 2015 23:02:09 +0000
ETag: "35676ce12ba0543c84489f3c393f5491"
Last-Modified: Mon, 07 Sep 2015 23:02:09 +0000
Content-Length: 245
X-API-Version: 1
Content-Type: application/json

    "status": 200,
    "data": {
        "id": 1,
        "name": "Test 1",
        "authentication_scheme": "NONE",
        "resource_type": "test",
        "resource_url": ""
    "resource": "test"

An API response has the status line, HTTP response headers (e.g., ETag) and often the body.

Status code

An API response as a HTTP response includes the HTTP status code that can have the following values:

Code Message Description
200 OK The default code for successful responses.
201 Created A resource has been created.
304 Not Modified The cached resource has not been modified. Responses with this code do not include the body.
See also Caching.
400 Bad Request The request was malformed (and needs to be fixed before retrying).
401 Unauthorized The resource requires the user to be authenticated. See also Authentication.
403 Forbidden The access to the resource is not allowed for the user.
404 Not Found The resource does not exist or has been removed.
405 Method Not Allowed Used HTTP method is not supported for the resource.
406 Not Acceptable The Accept HTTP header of the request is missing or does not allow application/json.
See Request.
412 Precondition Failed The request included a condition, that failed. See also Caching.
426 Upgrade Required The API client or the system license should be upgraded.
429 Too Many Requests The request has been rate limited. See also Rate Limiting.
454 Session Not Found The session could not be loaded. See Authentication.
500 Internal Server Error There was an error on the server.


The API service avoids using HTTP headers for delivering important information to API clients, except the Retry-After header that is described in Rate Limiting and the X-CSRF-Token header that is described in Security.


The body of the API response is a special JSON object, that delivers meta data and resource information to the API client.

Main fields

Here are the most important fields of the response message:

The value of this field is (normally) identical to the HTTP status code of the API response.
This field delivers the main information. It contains either the resource or the collection (i.e. array of resources).
This field contains the type of the resource delivered in the data field. For collections it's the type of the contained resource.
Total Count
This field is returned only with collections and contains the total number of items in the collection.

Errors, notifications and logs

The response can include three types of special messages:

  • Errors are intended for API clients (and, therefore, are not localized).
  • Notifications are intended for end users (and are localized).
  • Logs are to be logged by API clients and are intended for their developers and maintainers.


A response indicates an error, if its status is not 200 (OK) or 201 (Created) and the errors response field contains one or more error objects.

If the API client receives a response with error(s), it should analyze the code field of each error object and perform appropriate actions (report the error to the user, fix the request and retry, and so on).

Some error objects can include the following additional fields:

The `parameter` field holds the name of the parameter, that caused the error.
If there are several parameters, that caused the error, they are listed in the `parameters` field.
If the parameter is an array or a JSON object, the error object can additionally include the `pointer` field containing the exact path to the value in the parameter.


    "status": 400,
    "errors": [
            "code": "RESOURCE_ACTION_NOT_AVAILABLE",
            "message": "Not supported method, misspelled action name or action is not available for the resource",
            "more_info": ""

See also Errors for what each error code means.


Any response, successful or not, can include one or more notification objects in the notifications field.

The notification object contains the type field, that indicates the severity of the message.

The type can be:

  • INFO

Each notification message (of any type) must be displayed to the user by the API client.

Additionally, the notification object can include the following fields:

If the sticky field is set to true, the corresponding notification message should remain on the screen of the API client as reasonably long as possible.
Related URL
If the related_url field contains a URL, the API client may provide a UI element somewhere in the notification window, that would allow the user to check the resource represented by this URL. Or:
Related HREF
If the related_href field contains a URL, the API client should provide a UI element somewhere in the notification window, that would allow the user to open this URL in a browser.
Related label
If the related_label field is specified, its value should be used as a label for the aforementioned UI element.


    "status": 200,
    "notifications": [
            "type": "INFO",
            "message": "A message has been sent to your email",


Any response, successful or not, can include one or more log messages in the logs field.

The log object contains the level field, that indicates the severity of the problem.

The level can be:


Logs are intended for developers and administrators of the API client and contain important information about issues in its code or configuration. Therefore, the API client should write logs to some place, where developers and administrators can read them.


    "status": 200,
    "logs": [
            "level": "NOTICE",
            "message": "To avoid long delays instead of supplying username and password with each request use just the session id"