Basic API usage

All BotEngine requests start with

The next segment of the URI path depends on the type of request. For example: to get or modify entities.

Access Tokens

Each license has two tokens:

Developer access token

This token is only for you and allows you to doing requests to our API. This token should be never shared publicly because it gives full access to your account

Client access token

This token is not as dangerous as it allows only for /query endpoint requests. It can be kept as part of an application whose code may be readed by third persons. In necessary it can be regenerated any time in BotEngine settings.


Example request

curl -X GET "{path}" \
-H 'authorization: Bearer ${ACCESS_TOKEN}'

Each API method requires an authorization header with the corresponding token. All endpoints require a Developer access token. The only exception is endpoint /query which requires a Client access token that is potentially less dangerous.

For each API request, include this HTTP header:

Authorization: Bearer ${ACCESS_TOKEN}

Error handling

Errors are returned using standard HTTP error code syntax. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error (bad or missing parameters, not authenticated etc.), and codes in the 5xx range indicate an error with BotEngine servers. Any additional info is included in the status of the return call, JSON-formatted.

HTTP status codes summary

  • 400 – The request was incorrect, please make sure that passed arguments are matching format in method's documentation.
  • 401 – Unauthorized. You attempt to authenticate with an invalid authorization headers.
  • 404 – Not Found. You attempt to request a resource which doesn't exist.
  • 500 – Internal Server Error. Something unexpected happened on our end. Please try again or contact support.

Data format

BotEngine returns data in JSON format. See the following example.

  "timestamp": "2017-04-12T13:30:07.445Z",
  "status": {
    "code": 200,
    "errorType": "success"