Skip to main content

Overview

The ChatKitty Platform API provides a RESTful Application Programming Interface for administrators and server-side back-ends to configure and manage their ChatKitty applications. This API lets you create users and channels, send system messages and even delete your application. Everything you see on your ChatKitty dashboard can be controlled with the Platform API.

Schema​

All API access is over HTTPS, and accessed from https://api.chatkitty.com. All data is sent and received as JSON or multipart files.

curl -I https://api.chatkitty.com

HTTP/2 200
date: Mon, 27 Jun 2022 19:17:48 GMT
content-type: application/json
content-length: 1042
x-response-token: BF1E269D770E4A10B1DADAF2DA8C8624
x-api-version: v1.15.13
vary: Origin
vary: Access-Control-Request-Method
vary: Access-Control-Request-Headers
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
strict-transport-security: max-age=63072000 ; includeSubDomains ; preload
x-frame-options: DENY

Blank fields are omitted instead of being included as null.

All timestamps are returned in UTC time, ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Authentication​

The ChatKitty Platform API uses OAuth 2.0 Bearer access tokens to authenticate applications and administrators.

OAuth 2.0 Bearer access tokens are issued on behalf your application to access protected application resources.

OAuth2 bearer token (sent in a header)​

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.chatkitty.com
note

ChatKitty recommends sending OAuth tokens using the Authorization header.

Read more about OAuth2. OAuth2 tokens can be acquired using the client credentials flow for ChatKitty applications.

Parameters​

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

curl -i "https://api.chatkitty.com/v1/users?name=jdoe"

In this example, '1' is provided for the :application_id parameter in the path while :name is passed in the query string.

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json':

curl -i -d '{"type":"PUBLIC","name":"daily-discussion"}' https://api.chatkitty.com/v1/channels

Application root endpoint​

You can issue a GET request to your application's root endpoint to get the application's resource representation and all the endpoint categories that the Platform API supports:

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.chatkitty.com/v1/application

Client errors​

The Platform API may return any of these HTTP error codes:

All error objects have resource and field properties so that your client can tell what the problem is. There's also an error code to let you know what is wrong with the field. These are the possible validation error codes:

HTTP redirects​

The Platform API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

HTTP verbs​

The Platform API uses standard HTTP verbs with RESTful semantics for all actions.

Hypermedia​

All resources may have a _links property with one or more properties linking to other resources. These are meant to provide explicit URLs so that proper API clients don't need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers. All URLs are expected to be proper RFC 6570 URI templates.

You can then expand these templates using something like the url-template package:

template.parse('/v1/channels{?members}').expand({'members': 'jdoe,asmith'})
note

ChatKitty's Platform API implements the HAL hypermedia specification.

Pagination​

Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the page parameter. For some resources, you can also set a custom page size up to 100 with the size parameter.

Note that page numbering is 0-based and that omitting the page parameter will return the first page.

Some endpoints use cursor-based pagination. A cursor is a value that points to a location in the result set. With cursor-based pagination, there is no fixed concept of "pages" in the result set, so you can't navigate to a specific page. Instead, you can traverse the results by using the start or next parameters.

For more information on pagination, check out our guide on Traversing with pagination.

Reference Documentation​

For a complete description of functionality provided by the Platform API description check out the ChatKitty Platform API reference documentation.

If you have any problems or requests, please contact ChatKitty Support.