# Get Started

API Reference
Versioning
Responses and Errors
Envelopes
Authorization

# API Reference

The Keaze API is organized around REST, and it has predictable resource-oriented URLs, accepts JSON-encoded request bodies and returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

As Keaze powers multiple portals, you should send the header Portal-Id, with the portal id provided. If this header is not sent, the API will assume it's Keaze portal.

You can use the Keaze API in test mode, which does not affect live data.

# Versioning

When backwards-incompatible changes are made to the API, a vew version is released. Currently, there's only one version: 1. When releasing new versions in the future, the API upgrades guide will contain the changelogs.

To set the API version on a specific request, send a Version-Accept header with the numeric value of the version, otherwise the latest available version will be used.

# Responses and Errors

Any API request will receive a standard HTTP response code.

# Response Ranges

2xx: Sucessful request

4xx: Failed Request (Client error)

5xx: Failed Request (Server error)

# Common response codes are

HTTP Status Code	Description	Verbs
200 OK	Successful.	GET, PUT, PATCH, DELETE
201 Created	Created.	POST
400 Bad Request	Bad input parameter. Error message should indicate which one and why.	All
401 Unauthorized	Missing or bad authentication.	All
403 Forbidden	The client or user is authenticated but isn’t authorised to perform the requested operation on the given resource.	All
404 Not Found	Resource not found, usually when ID not found or invalid. When using GET for collections, it will never return 404, but an empty data array.	GET, PUT, PATCH, DELETE
405 Method Not Allowed	The resource doesn't support the specified HTTP verb.	All
409 Conflict	Conflict. Duplicate data or invalid data state would occur.	POST
422 Unprocessable Entity	Usually when there are validation errors. Attribute `message` will contain the kind of error, attribute `errors` will contain the list of errors related to each parameter.	POST, PUT, PATCH
500 Internal Server Error	Servers are not working as expected. The request is probably valid but needs to be requested again later.	All
503 Service Unavailable	Service Unavailable.	All

# Envelopes

When returning single objects no envelope will be used.

For collections, an envelope will be always used, which will contain the field data for the collection.

{
  "data": [items]
}

Paginated collections envelopes will also contain two more attributes, pagination and links, with the following structure:

{
  "data": [items],
  "pagination": {
    "currentPage": 2, // current page number
    "perPage": 10,    // number of items to be shown per page
    "total": 212,     // total number of items
    "from": 11,       // number of the first item in the result
    "to": 20,         // number of the last item in the result  
    "lastPage": 23,   // last page number
  }
  "links": {
    "first": "url to the first page",
    "prev": "url to the previous page",
    "next": "url to the next page",
    "last": "url to the last page",
  }
}

# Authorization

To access customer private resources, you will need an access token. This can be obtained by using one of the different endpoints when requesting access to the Portal.

To use the access token send the header Authorization with value Bearer {access_token} in every request that require authorization.

Keaze platform guide →