Change Log

2024-01-31

New endpoint
- GET /api/external/chatbot/conversation_uids
Update endpoints
- POST /api/external/chatbot/conversation: add parameter nickname
- GET /api/external/chatbot/messages: add parameter nickname

2023-11-10

New endpoints
- POST /api/external/chatbot/train
- GET /api/external/chatbot/models
- PATCH /api/external/chatbot/model_id
- POST /api/external/chatbot/conversation
- GET /api/external/chatbot/messages

Introduction

Welcome to the CaiGunn API! You can use our API to setup and interact with chatbot.

We have language bindings in Shell and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

CaiGunn uses API keys to allow access to the API. You can register and create chatbot at CaiGunn.

CaiGunn API expects for the API key to be included in all API requests to the server in a header that looks like the following:

api-key: CHATBOT_API_KEY

You must replace CHATBOT_API_KEY with your personal API key.

Model

Train a Model

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/train' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{"text": TEXT, "title": TITLE, "model_name": MODEL_NAME}'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/train"

payload = json.dumps(
    {"text": TEXT, "title": TITLE, "model_name": MODEL_NAME}
)
headers = {"api-key": CHATBOT_API_KEY, "Content-Type": "application/json"}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.json())

The above command returns JSON structured like this:

{
  "id": "11111111-1111-1111-1111-111111111111"
}

Train a model by text content.

HTTP Request

POST https://caigunn-api.ap-mic.com/api/external/chatbot/train

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.

Request Body Schema

Name	Type	Mandatory	Default	Description
text	string	true		Text for model training.
title	string	true		Title for the trained model.
model_name	string	false	"PaLM2"	"PaLM2", "gpt-3.5-turbo", "gpt-4"

Get All Models

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/models' \
    --header 'api-key: CHATBOT_API_KEY'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/models"

headers = {"api-key": "CHATBOT_API_KEY"}

response = requests.request("GET", url, headers=headers)

print(response.json())

The above command returns JSON structured like this:

{
  "models": [
    {
      "title": "string",
      "id": "string",
      "updated_at": "2023-11-06T09:09:41.552Z",
      "created_at": "2023-11-06T09:09:41.552Z",
      "model_name": "chat-bison"
    }
  ]
}

This endpoint retrieves all models.

HTTP Request

GET http://caigunn-api.ap-mic.com/api/external/chatbot/models

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.

Update Chatbot Model

curl --location --request PATCH 'https://caigunn-api.ap-mic.com/api/external/chatbot/model_id' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{"id": MODEL_ID}'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/model_id"

payload = json.dumps({"id": MODEL_ID})
headers = {"api-key": CHATBOT_API_KEY, "Content-Type": "application/json"}

response = requests.request("PATCH", url, headers=headers, data=payload)
print(response.json())

The above command returns JSON structured like this:

{
  "detail": "Update successfully"
}

This endpoint updates the model of chatbot.

HTTP Request

PATCH https://caigunn-api.ap-mic.com/api/external/chatbot/model_id

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.

Request Body Schema

Name	Type	Mandatory	Default	Description
id	string	true		Model id.

Conversation

Conversation With Chatbot

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/conversation&nickname=NICKNAME' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'uid: CUSTUM_UID' \
    --header 'Content-Type: application/json' \
    --data '{"text": TEXT}'

import requests
import json

url = "http://caigunn-api.ap-mic.com/api/external/chatbot/conversation&nickname=NICKNAME"

payload = json.dumps({"text": TEXT})
headers = {"api-key": CHATBOT_API_KEY, "uid": CUSTUM_UID, "Content-Type": "application/json"}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.json())

The above command returns JSON structured like this:

{
  "text": "string"
}

Send message to chatbot and get response.

HTTP Request

POST https://caigunn-api.ap-mic.com/api/external/chatbot/conversation

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
uid	string	true		Custom UID for identify conversation.

Query Parameters

Name	Type	Mandatory	Default	Description
nickname	string	false		Nickname of the conversation participant.

Request Body Schema

Name	Type	Mandatory	Default	Description
text	string	true		Message from the conversation participant.

Get Historical Messages

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/messages?offset=OFFSET&limit=LIMIT&start_at=START_AT&end_at=END_AT&nickname=NICKNAME' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'uid: CUSTUM_UID'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/messages?offset=OFFSET&limit=LIMIT&start_at=START_AT&end_at=END_AT&nickname=NICKNAME"

headers = {"api-key": CHATBOT_API_KEY, "uid": CUSTUM_UID}

response = requests.request("GET", url, headers=headers)

print(response.json())

The above command returns JSON structured like this:

{
  "messages": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "receive": "string",
      "send": "string",
      "type": "text",
      "id": "string",
      "log_type": "string",
      "kwargs": {}
    }
  ]
}

This endpoint retrieves historical messages from a conversation.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/chatbot/messages

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
uid	string	true		Custom UID for identify conversation.

Query Parameters

Name	Type	Mandatory	Default	Description
offset	integer	false	0
limit	integer	false	30
start_at	datetime	false
end_at	datetime	false
nickname	string	false		Nickname of the conversation participant.

Get Conversation UIDs

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/conversation/uids?offset=OFFSET&limit=LIMIT&start_at=START_AT&end_at=END_AT' \
    --header 'api-key: CHATBOT_API_KEY'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/conversation/uids?offset=OFFSET&limit=LIMIT&start_at=START_AT&end_at=END_AT"

headers = {"api-key": CHATBOT_API_KEY, "uid": CUSTUM_UID}

response = requests.request("GET", url, headers=headers)

print(response.json())

The above command returns JSON structured like this:

{
  "uids": [
    {
      "uid": "string",
      "nickname": "string",
      "source": "string",
      "last_sent": "string",
      "last_sent_at": "string"
    }
  ]
}

This endpoint retrieves conversation UIDs.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/chatbot/conversation/uids

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.

Query Parameters

Name	Type	Mandatory	Default	Description
offset	integer	false	0
limit	integer	false	30
start_at	datetime	false	1970-1-1	Get UIDs where last_sent_at is greater than or equal start_at.
end_at	datetime	false	current datetime	Get UIDs where last_sent_at is less than or equal end_at.

Errors

The CaiGunn API uses the following error codes:

Error Code	Meaning
400	Bad Request.
401	Unauthorized.
403	Forbidden.
404	Not Found.
405	Method Not Allowed.
406	Not Acceptable.
500	Internal Server Error.
503	Service Unavailable.