The Keaz API is REST-like and primarily uses JSON as the data encapsulation mechanism. Resources are accessed as top-level path components as detailed in the Resources sections below.

Resource Hashes

Fequently throughout this documentation, references are made to things like { VEHICLE HASH } or { USER HASH }. This is a means of referring to the basic hash for a resource as it is stored in the datastore. It generally contains all of the resource’s fields and a few house-keeping fields like id and location.


Some fields are automatically removed prior to being returned. An example of this is the password field in a { USER HASH }.

Fields, Uniqueness, and Validation

Each resource is comprised of one or more fields. There are two attributes a field may have which affect its usage:

  • Unique - unique fields must contain values that do not already exist for that resource type. - values are not namespaced, so expect collisions.
  • Validation - a field may have a value for validation which is a regular expression or a list of acceptable values.

The documentation for each resource contains the details of the required fields and which of the above conditions may apply.

Field Types

Fields are not typed and excluding validation expressions, are not checked for appropriateness by the API layer. Submitted, and, for the most part, retrieved data is handled as a string.

Dates and Times in Bookings

When manipulating or fetching bookings, dates and times are provided through the path to the resource.

GET /branch/1/bookings/2014-01-01/08:00/2014-01-02/06:00

An attempt by the API to interpret the date format automatically will occur, but for explicitness, it is best to use ISO dates. All times must be devoid of minutes or seconds - all bookings work on an hourly basis.

Within the documentation, any path which requires date time strings will use the shorthand DATETIMEPATH

GET /vehicle/4/bookings/DATETIMEPATH


All requests require the presence of a token query parameter:

GET http://server.name/resource/ID?token=TOKEN_VALUE

Tokens can be retrieved from the /login endpoint in exchange for a valid email and password.

Operation: POST /login
Request body:
    'email': 'someone@somewhere.fake',
    'password': 'hereitisbigboy'
Status: 200 OK
Response body:
    "token": "somelongandunreadablevalue"

The login path also supports GET requests. Currently this is used to serve data required for logging in such as company assets.


Each request made to the api passes through an authorization handler with the exceptions of the following paths:

  • /login
  • /tsco-health
  • /resetpassword
  • /activate

In addition, a required HTTP header HTTP-X-Source-Host must be passed in which contains the subdomain for the request. This is how requests are tied to companies.

Each user is assigned a set of permissions and those permissions roll-out to a list of low-level API operations. Refer to the code in api/utils/__init__.py for the gory details.

The requested path and action (HTTP verb) are compared to the list of permissions to determine whether or not the user is allowed access. In the event that a user is not allowed access, a 401 Forbidden is raised.

Generic Query Params

Most GET requests support the following query paramters:

  • orderby - supply a field name for the resource being retrieved to sort by that field.
  • reverse - set the value of this query parameter to something truthy to reverse the sort direction.
  • q - query results by a resource’s primary description field.


The use of q is resource-specific in terms of the field which will be filtered and the documentation for each resource reflects this. A good rule of thumb, however, is to assume the filtering will be done on the name field for the resource.

Operation: GET /companies?q=bang
Status: 200 OK
Response body:
    {'name': 'Big Bang Corp', ... },
    {'name': 'BangBang Guns LTD', ...},

Reset Password

By performing a GET against /login/reset along with an email in the query string, password resets can be requested. An email is sent with a ticket that can be posted back to /login/reset/TICKET along with a field called password in the request body.