Introduction

The Kayako API (the API) is our proprietary REST API implementation.

The API is based on resources. A resource is an object that the API end point fetches and/or manipulates. A collection (an array of resources) is a resource as well.

A resource can support the following basic REST API actions (that are actually HTTP methods):

GET for retrieving the resource
POST for creating the resource
PUT for modifying the resource
DELETE for removing the resource

Available API Endpoints

General

Request

To perform an API action you need to make an API request.

Actions can support "arguments" - variables that are specified in the query string of the HTTP request (they should be added to the URI in the request line). There are "common" API arguments (like fields, see Partial Output), which can be used for all API requests. Among these common arguments there are also special "server" arguments, that start with _ (e.g., _empty, see Special Options).

In addition to arguments the API intensively uses HTTP headers (which are preferred, if argument-based alternatives exist). Thus, caching and concurrency control are implemented using If-Match, If-None-Match, If-Modified-Since and If-Unmodified-Since HTTP headers (see Caching).

Main properties of resources are to be sent using "parameters" - variables that are delivered in the request body (which is used only for POST and PUT actions). The request body is usually formatted accordingly to the application/x-www-form-urlencoded content type (see Request).

Here is a sample API request to the Test end point:

POST /api/v1/tests?_empty=false HTTP/1.1
Host: brewfictus.kayako.com
Accept: */*
Content-Length: 43
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

name=Caryn+Pryor&array_items=1,2,3&is_boolean=true

And here is how CURL can be used to send such request:

curl -X POST \
     -d name=Test \
     -d array_items=1,2,3 \
     -d is_boolean=true 'https://brewfictus.kayako.com/api/v1/tests&_empty=false'

Response

An API request, that has been sent to the API service, returns an API response.

The HTTP status code of the API response is the first thing to check for errors (except JSONP, see Using JavaScript).

API responses come with the response body (except cached responses, see Caching), that delivers the special response JSON message. The response message contains the resource (if any) under the special data field. In addition, the message contains the status field, that delivers the HTTP status code, and can contain errors, notifications, logs and more (see Response).

Here is a sample of an API response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 10 Sep 2015 16:17:04 GMT
Expires: Thu, 10 Sep 2015 16:17:04 +0000
ETag: "c5096115d7d05d842514f96831aa852f"
Last-Modified: Thu, 10 Sep 2015 16:17:04 +0000
Content-Location: https://brewfictus.kayako.com/api/v1/tests/99
Content-Length: 369
X-API-Version: 1

{
    "status": 201,
    "data": {
        "id": 99,
        "name": "Caryn Pryor",
        "authentication_scheme": "NONE",
        "array_items": [
            1,
            2,
            3
        ],
        "is_boolean": true,
        "resource_type": "test",
        "resource_url": "https://brewfictus.kayako.com/api/v1/tests/99"
    },
    "resource": "test"
}

Authentication

The vast majority of API end points require the user to be authenticated.

The easiest way to authenticate is to use the standard Basic HTTP authentication scheme (there is also a more flexible OAuth 2.0 scheme, see Authentication). The Basic HTTP scheme expects the username and password to be base64-encoded and added to the Authorization HTTP header as follows (check also this page):

Authorization: Basic base64($username:$password)

This authentication scheme is also supported by CURL:

curl -u norton.low@eyecloud.com:B2WwHWTJzI49NM \
     'https://brewfictus.kayako.com/api/v1/tests&fields=*'

Testing

To test the Kayako API you can use the special public Test resource.

For example:

GET

To retrieve multiple test resources:

curl 'https://brewfictus.kayako.com/api/v1/tests?_empty=false&count=45'

To retrieve the test resource with ID = 1:

curl https://brewfictus.kayako.com/api/v1/tests/1

POST

To create a test resource:

curl -X POST \
     -d 'name=Caryn Pryor' \
     -d array_items=1,2,3 \
     -d is_boolean=true \
     -d option=BAR \
     -d binary_data=Q2FyeW4gUHJ5b3I= https://brewfictus.kayako.com/api/v1/tests

PUT

To update the test resource with ID = 1:

curl -X PUT \
     -d is_boolean=false \
     -d option=NONE https://brewfictus.kayako.com/api/v1/tests/1

To update multiple test resources at once:

curl -X PUT \
     -d option=ANY 'https://brewfictus.kayako.com/api/v1/tests?ids=1,2,3'

DELETE

To remove the test resource with ID = 999:

curl -X DELETE https://brewfictus.kayako.com/api/v1/tests/999

To remove multiple test resources at once:

curl -X DELETE 'https://brewfictus.kayako.com/api/v1/tests?ids=997,998,999'