API Documentation

Please use our our swagger documentation https://app.kolas.ai/api/documentation. For testing API use credentials (client ID and client secret) generated in your account settings https://app.kolas.ai/pages/account-setting

For generating your API clients you can use our OpenApi schema on GitHub.

Here’s a step-by-step guide to using the Kolas.Ai API:

Register and Obtain an OAuth2 Token

To use the API, you need to authenticate via OAuth2 and obtain an access token.

Obtain the Client ID and Client Secret for your application.

Use these credentials to request a token by sending a POST request to the token endpoint:

Request:

POST /oauth/token 
Content-Type: application/x-www-form-urlencoded

Request Body:

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

In the response, you’ll receive an access_token that you’ll use to authenticate API requests.

Make Sync Prediction for Messages

Once you have your access token, you can make a request to predict the category of your messages.

Send a POST request to the /predictions/predict endpoint:

Request:

POST /predictions/predict 
Authorization: Bearer YOUR_ACCESS_TOKEN 
Content-Type: application/json

Request Body should include two required parameters:

projectId: The ID of the project configured for predictions.messages: An array of messages for which you want to make a prediction.Example request body:

{
  "projectId": 3457,
  "messages": [
    {
      "messageId": "75a292aa-5f91-5a7f-e970-4cfc8bd8da30",
      "message": "What did you do yesterday?"
    },
    {
      "messageId": "11a292aa-5f91-5a7f-e970-4cfc8bd8da10",
      "message": "Hello world!"
    }
  ]
}

Name	Type	Description
projectId	integer	ID of project
messages	array	list of messages for classification
messages.messageId	string	unique message identifier
messages.message	string	message for classification

Response will include the prediction for each message:

{
  "predictions": [
    {
      "messageId": "75a292aa-5f91-5a7f-e970-4cfc8bd8da30",
      "categories": [
        "Neutral",
        "Insult",
        "Spam"
      ],
      "prediction": "Neutral",
      "probability": "0.99808084964752",
      "message": "What did you do yesterday?"
    },
    {
      "messageId": "11a292aa-5f91-5a7f-e970-4cfc8bd8da10",
      "categories": [
        "Neutral",
        "Insult",
        "Spam"
      ],
      "prediction": "Neutral",
      "probability": "0.8446232676506",
      "message": "Hello world!"
    }
  ]
}

Name	Type	Description
predictions	array	list of predictions
predictions.categories	array	list of supported categories
predictions.prediction	string	predicted category
predictions.probability	string	probability of prediction (max value 1)
predictions.messageId	string	unique message identifier
predictions.message	string	processed message

Handle Errors

If your request fails, you’ll receive an error. The API provides several error codes:

401 Unauthorized: If the access token is missing or invalid. Example response:

{ 
  "message": "Unauthenticated." 
}

422 Validation Error: If there’s a validation issue with the request (e.g., missing required fields). Example response:j

{
 "errors": ["Missing projectId field."],
 "message": "Validation exception" 
}

5XX Server Error: If an unexpected error occurs on the server. Example response:

{
 "message": "Internal server error. Contact technical support." 
}

Notes:

Ensure that the projectId exists and is properly configured in the Kolas.Ai system.
Before using the API in a production environment, it’s recommended to test requests using tools like Postman or cURL.

If you encounter any questions or issues, feel free to ask!

Error codes

PROJECT_NOT_FOUND – There is no project with the ID passed in the request. Check your project ID.
PROJECT_DATASET_NOT_CONFIGURED – No datasets are enabled in the project. Check your project settings.
PROJECT_NOT_ACTIVE – The project is disabled. Enable the project or pass another project ID.
ACCOUNT_BALANCE_EMPTY – You have used all your credits. Top up your account balance.

Make Async Prediction for Messages

Send a POST request to the /predictions/asyncPredict endpoint:

Request:

POST /predictions/asyncPredict 
Authorization: Bearer YOUR_ACCESS_TOKEN 
Content-Type: application/json

Request Body should include two required parameters:

projectId: The ID of the project configured for predictions.messages: An array of messages for which you want to make a prediction.Example request body:

{
  "projectId": 3457,
  "messages": [
    {
      "messageId": "75a292aa-5f91-5a7f-e970-4cfc8bd8da30",
      "message": "What did you do yesterday?"
    },
    {
      "messageId": "11a292aa-5f91-5a7f-e970-4cfc8bd8da11",
      "message": "Hello world!"
    }
  ]
}

Name	Type	Description
projectId	integer	ID of project
messages	array	list of messages for classification
messages.messageId	string	unique message identifier
messages.message	string	message for classification

Response will be send to your webhook and it will include the prediction for separate message:

Header

{
  "user-agent": "GuzzleHttp/7",
  "content-length": "206",
  "content-type": "application/json",
  "idempotency-key": "75a292aa-5f91-5a7f-e970-4cfc8bd8da30",
   "x-signature": "bb8e06164145174cc662418c5c3829c2511fb1ce4c33ce210bb68308c6469074",
  "accept-encoding": "gzip"
}

Name	Type	Description
idempotency-key	string	Unique identifier of message
x-signature	string	It is cryptographic signature of message. The sha256 algorithm is used for generation.

Body

{
  "messageId": "11a292aa-5f91-5a7f-e970-4cfc8bd8da11",
  "message": "Hello world!"
  "predictions": [
   {
     "categories": [
       "Neutral",
       "Insult",
       "Spam"
     ],
     "prediction": "Neutral",
     "probability": "0.8446232676506",
   }
  ]
}

Name	Type	Description
predictions	array	list of predictions
predictions.categories	array	list of supported categories
predictions.prediction	string	predicted category
predictions.probability	string	probability of prediction (max value 1)
messageId	string	unique message identifier
message	string	processed message