NAV Navbar
shell http python javascript java
  • Introduction
  • Authentication
  • Conversation
  • Errors
  • Introduction

    Welcome to ChatEngine! We provide a quality API for conversational chatbots. Simply make an request, and get a response back for your input! It works just like Cleverbot, but faster.

    We have example API code for Shell, Python, JavaScript, and Java. Check them out by switching programming languages with the tabs on the side.

    All POST endpoints accept data in JSON format (MIME type: application/json). Support for form body (MIME type: application/x-www-form-urlencoded) data may be added soon.

    Libraries/clients used:

    Authentication

    To authorize, use this code:

    curl "api_endpoint"
      -H "Authorization: super_secret_key"
    
    GET api_endpoint
    Authorization: super_secret_key
    
    import requests
    
    requests.get('api_endpoint', headers={'Authorization': 'super_secret_key'})
    
    const request = require('request');
    
    request.get({
        'url': 'api_endpoint',
        'headers': {
            'Authorization': 'super_secret_key'
        }
    }, (error, response, body) => {
    
    });
    
    import okhttp3.OkHttpClient;
    import okhttp3.Response;
    import okhttp3.Request;
    
    OkHttpClient client = new OkHttpClient();
    Response response = client.newCall(new Request.Builder()
            .get()
            .url("api_endpoint")
            .header("Authorization", "super_secret_key")
            .build()).execute();
    response.body().close();
    

    Be sure to replace super_secret_key with your API key.

    ChatEngine uses API keys to authenticate and identify clients. With every request, you must include a header that looks like this:

    Authorization: super_secret_key

    Conversation

    Ask

    curl "https://chatengine.xyz/api/ask"
      -XPOST
      -H "Content-Type: application/json"
      -H "Authorization: super_secret_key"
      -d '{"session": "session_id-101", "query": "Hi there!"}'
    
    GET /api/ask
    Content-Type: application/json
    Authorization: super_secret_key
    
    {
        "session": "session_id-101",
        "query": "Hi there!"
    }
    
    import json
    import requests
    
    data = {
        'session': 'session_id-101',
        'query': 'Hi there!'
    }
    
    response = requests.post('https://chatengine.xyz/api/ask',
                            headers={'Authorization': 'super_secret_key'}, data=json.dumps(data))
    
    response_data = json.loads(response.text)
    
    const request = require('request');
    
    request.post({
        'url': 'https://chatengine.xyz/api/ask',
        'headers': {
            'Authorization': 'super_secret_key'
        }
    }, (error, response, body) => {
        let responseData = JSON.parse(response);
    });
    
    import okhttp3.OkHttpClient;
    import okhttp3.Response;
    import okhttp3.Request;
    import okhttp3.RequestBody;
    import okhttp3.MediaType;
    import org.json.JSONObject;
    
    private static final MediaType JSON_MEDIA_TYPE = MediaType.parse("application/json; charset=utf-8");
    
    OkHttpClient client = new OkHttpClient();
    String response = client.newCall(new Request.Builder()
            .post(RequestBody.create(JSON_MEDIA_TYPE, new JSONObject()
                            .put("session", "session_id-101")
                            .put("query", "Hi there!")
                            .toString()))
            .url("https://chatengine.xyz/api/ask")
            .header("Authorization", "super_secret_key")
            .build()).execute().body().string();
    
    JSONObject responseData = new JSONObject(response);
    

    The above code returns JSON structured like this:

    {
        "success": true,
        "session": "session_id-101",
        "response": "Heya!",
        "confidence": 0.451
    }
    

    session will only be present if you didn't specify a session. In that case, please save the session ID for future requests (in the same conversation).

    If an error occurred, the JSON will be structured like this:

    {
        "success": false,
        "error": "You must specify some text!",
        "response": "An error occurred: You must specify some text!",
        "confidence": 0
    }
    

    This endpoint returns an answer for your query, as a step in a conversation.

    HTTP Request

    POST /api/ask

    Request Data

    Parameter Default Type Description
    session random string Used to identify the conversation, and provide context. A random one will be generated and returned if you don't specify one.
    query N/A string This parameter is required, as it is the whole intent of the endpoint.

    Errors

    The ChatEngine API uses the following error codes:

    Error Code Name Meaning
    400 Bad Request Your request is ill-formatted or missing data.
    401 Unauthorized Your API key is invalid.
    403 Forbidden That endpoint isn't available to your key's tier.
    404 Not Found That endpoint couldn't be found.
    405 Method Not Allowed You tried to use an endpoint with the wrong method.
    406 Not Acceptable You sent a format that's not JSON.
    410 Gone That endpoint has been removed.
    418 I'm A Teapot Tip me over and pour me out.
    429 Too Many Requests You're requesting too many things, too fast.
    500 Internal Server Error The server exploded processing your request.
    503 Service Unavailable We're temporarily offline for maintenance. Try again later.