KoroAI Gateway — API Documentation
Use Authorization: Bearer <token> for all APIs except login. Examples provided in cURL, Python, and JavaScript.
Authentication & Accounts
Individual account login.
Log into your personal account.
Use credentials you used when registering on KoroAI Mobile/ Web/ Windows/Linux Application.
Request Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
email |
string | Required | Registered email address for the account | Must be a valid registered email |
password |
string | Required | Account password for verification | Must match the stored password hash |
Example Request
{
"email": "myname@koroai.neta.co.ke",
"password": "MyPass123"
}
Response
{
"name": "My Name",
"phone": null,
"refresh": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAidXNlcl8zMTIwIiwgImlhdCI6IDE3NjE5OTE5NzcsICJleHAiOiAxNzYxOTk1NTc3LCAicm9sZSI6ICJhZG1pbiJ9.wGhhiVw6hDIoyRodztxqLnBkQ0NnzEjPOp-wOE3lVnQ"
"access": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAidXNlcl8zNTAzIiwgImlhdCI6IDE3NjE5OTE5MzMsICJleHAiOiAxNzYxOTk1NTMzLCAicm9sZSI6ICJhZG1pbiJ9.c7YPEvJLW2YjAn6JHhcHi4p-LwKtkE4uA8mJonrYd4E",
"user_id": 2,
"email": "myname@koroai.neta.co.ke",
"account_type": "individual",
"business_options": []
}
Error Responses
{
"error": "Invalid credentials"
}
Business account login
Log in as business user
Use credentials you used when registering on KoroAI Mobile/ Web/ Windows/Linux Applictaion.
Get business_id from KoroAI application under Profile/My Account
Request Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
email |
string | Required | Registered email address for the account | Must be a valid registered email |
business_id |
string | Required | Unique id for a business | Must be a valid business id |
password |
string | Required | Account password for verification | Must match the stored password hash |
Example Request
{
"email": "myname@koroai.neta.co.ke",
"business_id": "utyynmsdhhhhdsjjh768sdmnmmnsdnds",
"password": "MyPass123"
}
Response
{
"name": "My Name",
"phone": null,
"refresh": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAidXNlcl8zMTIwIiwgImlhdCI6IDE3NjE5OTE5NzcsICJleHAiOiAxNzYxOTk1NTc3LCAicm9sZSI6ICJhZG1pbiJ9.wGhhiVw6hDIoyRodztxqLnBkQ0NnzEjPOp-wOE3lVnQ",
"access": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAidXNlcl8zMTIwIiwgImlhdCI6IDE3NjE5OTE5NzcsICJleHAiOiAxNzYxOTk1NTc3LCAicm9sZSI6ICJhZG1pbiJ9.wGhhiVw6hDIoyRodztxqLnBkQ0NnzEjPOp-wOE3lVnQ",
"user_id": 3,
"email": "myname@koroai.neta.co.ke",
"account_type": "business",
"business_options": {
"business_user_role_id": 1,
"business_id": "utyynmsdhhhhdsjjh768sdmnmmnsdnds",
"business_name": "Neta",
"role_id": 1,
"role_name": "Admin"
}
}
Error Responses
{
"error": "Invalid credentials"
}
{
"error": "Business id is invalid"
}
{
"error": "Business/User relation not found"
}
Exchange refresh token for a new access token.
Request Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
refresh |
string | Required | Valid refresh token obtained during login | JWT format, must not be expired |
Example Request
{
"refresh": "jwt_refresh_token"
}
Response
{
"access": "new_access_token"
}
Error Responses
{
"error": "Token invalid",
"message": "Token is invalid or expired."
}
Request a password reset email.
Request Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
email |
string | Required | Email address associated with the account | Must be a registered email in the system |
Example Request
{
"email": "user@example.com"
}
Response
{
"message": "If an account with that email exists, a reset email has been sent. Check your email."
}
Error Responses
{"error": "Email is required"}
Dashboard summary stats for authenticated user.
Response
{
"projects": 4,
"image_categories": 4,
"images": 567,
"models": 5,
"predictions": 5,
}
Error Responses
{
"detail": "Authentication credentials were not provided."
}
Projects
List all projects for the authenticated user/business.
Response
[
{
"id": "fkjhsjhgkjhkhgjghgeywtoq6",
"name": "Disease Prediction",
"description": "This project holds models that predict diseases",
"created_at": "2025-10-04T12:51:58.815103Z"
},
{
"id": "sfjkghdslkhdkjhgdfkjhgkj",
"name": "Presidents Classiffier",
"description": "A CNN project to classifier presidents based on their images",
"created_at": "2025-10-01T17:39:26.586558Z"
}
]
Error Responses
{
"detail": "Authentication credentials were not provided."
}
Create a new project.
Request Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
name |
string | Required | Project name for identification | 3-100 characters, unique per user/business |
description |
string | Optional | Detailed description of the project purpose | Maximum 500 characters |
Example Request
{
"name": "Livestock Disease Prediction",
"description": "Livestock Disease Prediction Project"
}
Response
{
"id": "fjksahjskafhskjdfkjs",
"name": "Livestock Disease Prediction Project"
}
Error Responses
{
"name": [
"This field is required."
]
}
Images & Images Categories
List available image categories.
Response
[
{
"id": "6hghhghghg",
"name": "Viral Diseases",
"project_id": "etertteteetert2",
"project_name": "Livestock Disease Prediction",
"created_at": "2025-10-06T19:15:28Z"
},
{
"id": "ghghhgghhghg",
"name": "Bacterial Diseases",
"project_id": "etertteteetert2",
"project_name": "Livestock Disease Prediction",
"created_at": "2025-10-06T19:15:28Z"
},
]
Error Responses
{
"detail": "Authentication credentials were not provided."
}
Create a new image category.
Request Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
name |
string | Required | Project name for identification | 3-100 characters, unique per user/business |
project |
string | Optional | Selected project from the list of projects | Should be an existing project id |
Example Request
{
"name": "Viral Diseases",
"project": "fjksahjskafhskjdfkjs"
}
Response
{
"id": "fshjsdghsdfhgshdhjsdgh",
"name": "Viral Diseases",
"project": "fjksahjskafhskjdfkjs"
}
Error Responses
{
"name": [
"This field is required."
],
"project": [
"This field is required."
]
}
List available images.
Response
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "sdjkdsakjfskjfdsjjkjk",
"thumbnail": "https://koroai.neta.co.ke/viral.png",
"uploaded_at": "2025-10-06T19:47:39.424953Z",
"image_url": "https://koroai.neta.co.ke/viral.png",
"thumbnail_url": "https://127.0.0.1:8001/viral.png",
"category_name": "Viral Diseases",
},
{
"id": "ergdfhfghgfjghjghfjj",
"thumbnail": "http://koroai.neta.co.ke/bacterial.png",
"uploaded_at": "2025-10-01T18:20:19.382112Z",
"image_url": "https://koroai.neta.co.ke/bacterial.png",
"thumbnail_url": "https://koroai.neta.co.ke/bacterial.png",
"category_name": "Bacterial Diseases",
},
]
}
Error Responses
{
"detail": "Authentication credentials were not provided."
}
Upload an image to an image category.
Request Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
image |
file | Required | Image file to upload for processing | JPEG, PNG, JPEG; max 10MB |
category |
string | Required | Category ID for image classification | Must be a valid category ID |
Example Response
{
"id": "sdjkdsakjfskjfdsjjkjk",
"thumbnail": "https://koroai.neta.co.ke/viral.png",
"uploaded_at": "2025-10-06T19:47:39.424953Z",
"image_url": "https://koroai.neta.co.ke/viral.png",
"thumbnail_url": "https://127.0.0.1:8001/viral.png",
"category_name": "Viral Diseases",
}
Error Responses
{
"category": [
"This field is required."
],
"images": [
"This field is required."
]
}
{
"error": "File too large",
"message": "File size exceeds maximum allowed limit of 10MB."
}
Model Hub & Training
List trained models for user/business.
Response
[
{
"id": "6ghgghgfdhgff",
"name": "Presidents Classiffier model",
"description": null,
"project": "fdsdffsdfsddf",
"project_name": "Presidents Classiffier",
"tasks": [
{
"key": "image_classification",
"label": "Image Classification",
"description": "Classify images into categories.",
"label_mapping": {
"Obama": 0,
"Trump": 1
},
"training_inputs": [
{
"name": "images",
"type": "folder",
"details": [
{
"column_name": "folder_name",
"description": "Class label folder."
},
{
"column_name": "image_file",
"description": "Image file."
}
],
"description": "Folder of images organized by class."
}
]
}
],
"scope": "user",
"training_type": "custom",
"model_url": "https://koroai.neta.co.ke/mymodel.h5",
"version": 1,
"created_at": "2025-11-02T13:04:48.524097Z",
"framework": "tensorflow",
"input_type": "image",
"input_shape": null,
"model_identifier": null,
"target_column": null
},
{
"id": "vdghgghfhgghfhgf",
"name": "Heart Disease Prediction 2",
"description": null,
"project": "fsggfdsgdgsrere",
"project_name": "Tabular",
"tasks": [
{
"key": "classification_regression",
"label": "Classification/Regression",
"description": "Train model on data that has target as one column and all other columns as features",
"label_mapping": {
"Absence": 0,
"Presence": 1
},
"training_inputs": [
{
"name": "file",
"type": "file",
"details": [
{
"type": "numeric",
"column_name": "index"
},
{
"type": "numeric",
"column_name": "Age"
},
{
"type": "numeric",
"column_name": "Sex"
},
{
"type": "numeric",
"column_name": "Chest pain type"
},
{
"type": "numeric",
"column_name": "BP"
},
{
"type": "numeric",
"column_name": "Cholesterol"
},
{
"type": "numeric",
"column_name": "FBS over 120"
},
{
"type": "numeric",
"column_name": "EKG results"
},
{
"type": "numeric",
"column_name": "Max HR"
},
{
"type": "numeric",
"column_name": "Exercise angina"
},
{
"type": "numeric",
"column_name": "ST depression"
},
{
"type": "numeric",
"column_name": "Slope of ST"
},
{
"type": "numeric",
"column_name": "Number of vessels fluro"
},
{
"type": "numeric",
"column_name": "Thallium"
},
{
"type": "dropdown",
"choices": [
"Presence",
"Absence"
],
"column_name": "Heart Disease"
}
],
"description": "A CSV or JSON with feature columns and target columns"
}
],
"prediction_inputs": [
{
"name": "form_inputs",
"type": "form_inputs",
"details": [
{
"type": "numeric",
"column_name": "index"
},
{
"type": "numeric",
"column_name": "Age"
},
{
"type": "numeric",
"column_name": "Sex"
},
{
"type": "numeric",
"column_name": "Chest pain type"
},
{
"type": "numeric",
"column_name": "BP"
},
{
"type": "numeric",
"column_name": "Cholesterol"
},
{
"type": "numeric",
"column_name": "FBS over 120"
},
{
"type": "numeric",
"column_name": "EKG results"
},
{
"type": "numeric",
"column_name": "Max HR"
},
{
"type": "numeric",
"column_name": "Exercise angina"
},
{
"type": "numeric",
"column_name": "ST depression"
},
{
"type": "numeric",
"column_name": "Slope of ST"
},
{
"type": "numeric",
"column_name": "Number of vessels fluro"
},
{
"type": "numeric",
"column_name": "Thallium"
}
],
"description": "Filled form with all required values"
}
]
}
],
"scope": "user",
"training_type": "custom",
"model_url": "https://koroai.neta.co.ke/mymodel.pkl",
"version": 1,
"created_at": "2025-10-05T16:19:51.949653Z",
"framework": "scikit",
"input_type": "tabular",
"input_shape": null,
"model_identifier": null,
"target_column": "Heart Disease"
},
{
"id": "ffsgfdgfgfdgfddg",
"name": "Distill based Uncased",
"description": "Distill based Uncased",
"project": "sfgsfdfdfd",
"project_name": "Presidents Classiffier",
"tasks": [
{
"key": "text_classification",
"label": "Text Classification",
"description": "Classify text into categories such as sentiment, spam detection, or multi-label classification.",
"training_inputs": [
{
"name": "file",
"type": "file",
"details": [
{
"column_name": "text",
"description": "Text content to classify."
},
{
"column_name": "label",
"description": "Label(s) assigned to the text."
}
],
"description": "CSV/JSON file with text and labels."
}
]
},
{
"key": "ner",
"label": "Named Entity Recognition",
"description": "Extract entities like names, locations, and organizations from text.",
"training_inputs": [
{
"name": "file",
"type": "file",
"details": [
{
"column_name": "text",
"description": "Text containing entities."
},
{
"column_name": "entities",
"description": "Annotated entities with positions and labels."
}
],
"description": "CSV/JSON with text and annotated entities."
}
]
},
{
"key": "question_answering",
"label": "Question Answering",
"description": "Answer a question given a context passage.",
"training_inputs": [
{
"name": "file",
"type": "file",
"details": [
{
"column_name": "context",
"description": "Context passage."
},
{
"column_name": "question",
"description": "Question to answer."
},
{
"column_name": "answer",
"description": "Correct answer."
}
],
"description": "CSV/JSON file with context, questions, and answers."
}
]
}
],
"scope": "individual",
"training_type": "pretrained",
"model_url": "https://koroai.neta.co.ke/distilbert-base-uncased.zip",
"version": 1,
"created_at": "2025-10-02T20:07:04.186360Z",
"framework": "huggingface",
"input_type": "text",
"input_shape": null,
"model_identifier": "a3675324-074a-4cab-88a2-7d9e41324405",
"target_column": null
}
]
Image Model Prediction
Request Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
model |
string | Required | Model ID from the model hub to use for prediction | Must be a valid model ID from available models |
input_file |
file | Required for image models | List of images | Should be valid list of images |
task_key |
string | Required | Task key the model should use to predict | The task key should be an existing task under that model(e.g image_classification) |
input_text |
String | Required for tabular/Text Models | Text the model will try to predict based on training | For text models, it should be normal text while for tabular models it should be json(key value for each of the CSV features used in training) |
Example Response
[
{
"id": "34543egdg",
"model": "sdfdsdfsadfsdfs",
"input_text": "",
"output_text": "Obama",
"project": "sfsgfddsggdsf",
"predicted_at": "2025-11-02T13:27:58.552646Z",
"input_url": "https://koroai.neta.co.ke/obama.png",
"model_name": "Presidents Classiffier model",
"task_key": "",
"input_type": "image"
}
]
Error Responses
{"error": "Input file required"}
Task Applications
List task applications.
Response
[
{
"id": 1,
"task_name": "Text Classification",
"task_key": "text_classification",
"description": "Determine whether text expresses positive, negative, or neutral sentiment.",
"name": "Sentiment Analysis",
"key": "sentiment_analysis",
"label": "Enter text to analyze sentiment",
"hf_models": [
{
"id": "424223a0-0f68-4378-bd34-a76f0884079c",
"name": "xlm-roberta-base",
"description": null,
"uploaded_by": null,
"business": null,
"project": null,
"tasks": [
{
"key": "text_classification",
"label": "Text Classification",
"description": "Classify text into categories such as sentiment, spam detection, or multi-label classification.",
"training_inputs": [
{
"name": "CSV File",
"type": "file",
"details": [
{
"column_name": "text",
"description": "Sentence to classify"
},
{
"column_name": "labels",
"description": "Classification label"
}
],
"description": "A CSV file containing text and labels"
}
],
"prediction_inputs": [
{
"name": "text",
"type": "string",
"description": "List of text inputs"
}
]
},
{
"key": "ner",
"label": "Named Entity Recognition",
"description": "Extract entities like names, locations, and organizations from text.",
"training_inputs": [
{
"name": "JSON File",
"type": "file",
"details": [
{
"field": "sentence_id",
"description": "Id of the sentense"
},
{
"field": "sentence",
"description": "The sentence"
},
{
"field": "token",
"description": "The token"
},
{
"field": "label",
"description": "The label"
}
],
"description": "A JSON file with tokens and entity tags"
}
],
"prediction_inputs": [
{
"name": "text",
"type": "string",
"description": "Text to extract entities from"
}
]
},
{
"key": "question_answering",
"label": "Question Answering",
"description": "Answer a question given a context passage.",
"training_inputs": [
{
"name": "CSV File",
"type": "file",
"details": [
{
"field": "context",
"description": "Reference context"
},
{
"field": "question",
"description": "Question to answer"
},
{
"field": "answer",
"description": "The answer to the question"
}
],
"description": "CSV File containing context,question and answer"
}
],
"prediction_inputs": [
{
"name": "context",
"type": "string",
"description": "Reference text"
},
{
"name": "question",
"type": "string",
"description": "Question to answer"
}
]
}
],
"scope": "public",
"training_type": "pretrained",
"model_url": null,
"version": 1,
"created_at": "2025-12-01T17:04:13.902172Z",
"framework": "huggingface",
"input_type": "text",
"input_shape": null,
"model_identifier": null,
"target_column": null
},
],
"data_link": "https://www.kaggle.com/datasets?search=sentiment+analysis",
"created_at": "2025-12-01T17:06:00.180765Z",
"updated_at": "2025-12-04T13:17:35.368772Z"
},
{
"id": 12,
"task_name": "Text Generation",
"task_key": "text_generation",
"description": "Generate articles, blog posts, propasal, stories, poems etc",
"name": "Content Writing Assistant",
"key": "content_writing",
"label": "Enter topic or title",
"hf_models": [
{
"id": "273f9f25-12fe-4d30-b61a-111a9db687b1",
"name": "KoroAI 1.0",
"description": null,
"uploaded_by": null,
"business": null,
"project": null,
"tasks": [],
"scope": "public",
"training_type": "retrained",
"model_url": null,
"version": 1,
"created_at": "2025-12-01T17:06:00.166242Z",
"framework": "pytorch",
"input_type": "text",
"input_shape": null,
"model_identifier": null,
"target_column": null
},
{
"id": "6cabb955-36eb-4e0d-ba22-c21ccd6c0725",
"name": "bart-base",
"description": null,
"uploaded_by": null,
"business": null,
"project": null,
"tasks": [
{
"key": "text_generation",
"label": "Text Generation",
"description": "Generate human-like text based on a given prompt.",
"training_inputs": [
{
"name": "Text File",
"type": "file",
"description": "Plain text file used for fine-tuning a language model"
}
],
"prediction_inputs": [
{
"name": "prompt",
"type": "string",
"description": "Starting prompt for generation"
},
{
"name": "max_tokens",
"type": "number",
"description": "Max length of generated text"
}
]
},
{
"key": "text_summarization",
"label": "Text Summarization",
"description": "Summarize long text into shorter versions.",
"training_inputs": [
{
"name": "CSV File",
"type": "file",
"details": [
{
"column_name": "text",
"description": "Original long text"
},
{
"column_name": "summary",
"description": "Short summary"
}
],
"description": "CSV with text and summary columns"
}
],
"prediction_inputs": [
{
"name": "text",
"type": "string",
"description": "Text to summarize"
}
]
}
],
"scope": "public",
"training_type": "pretrained",
"model_url": null,
"version": 1,
"created_at": "2025-12-01T17:04:14.102567Z",
"framework": "huggingface",
"input_type": "text",
"input_shape": null,
"model_identifier": null,
"target_column": null
},
],
"data_link": "https://www.kaggle.com/datasets?search=content+writing",
"created_at": "2025-12-01T17:06:00.364975Z",
"updated_at": "2025-12-04T13:17:35.488728Z"
},
]
Task Application Prediction API. Supports multiple task types including text, document, translation, duplicate detection, content writing, synopsis, document search, and FAQ bots.
Request Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
task_app_key |
string | Required | Key of the task application | Must be a valid task application key |
model |
string | Required | Model ID from the model hub | Must refer to an existing model |
prompt |
string | Required for text-based tasks | Main text input | Required for text tasks like translation, content writing, FAQ bots, etc. |
document |
file | Required for document tasks | Document file for analysis or question answering | Required unless context is provided |
context |
string | Optional | Raw text instead of uploading a document | Required if document is missing (document_search) |
source_language |
string | Required for translation | Language of input text | Valid language |
target_language |
string | Required for translation | Target language | Valid language |
sentence1 |
string | Required for similarity/duplicate detection | First sentence | Required for duplicate detection or similarity tasks |
sentence2 |
string | Required for similarity/duplicate detection | Second sentence | Required for duplicate detection or similarity tasks |
category |
string | Required for content writing/synopsis | Content category | Must be a valid category |
size_category |
string | Required for content writing | Size variation (short/medium/long) | Only for content writing tasks |
size |
integer | Optional | Number of outputs | Default: 1 |
project |
string | Required for FAQ bots / Knowledge Base Assistant | Project ID for retrieval tasks | Must exist in user's workspace |
Example Requests
Text/Translation Task
curl -X POST https://koroai.neta.co.ke/model-hub/task-applications/predict/ \ -H "Authorization: Bearer <token>" \ -F "task_app_key=translation" \ -F "model=273f9f25-12fe-4d30-b61a-111a9db687b1" \ -F "prompt=Good morning" \ -F "source_language=en" \ -F "target_language=fr"
Duplicate Detection / Similarity Task
curl -X POST https://koroai.neta.co.ke/model-hub/task-applications/predict/ \ -H "Authorization: Bearer <token>" \ -F "task_app_key=duplicate_detection" \ -F "model=273f9f25-12fe-4d30-b61a-111a9db687b1" \ -F "sentence1=Obama visited Kenya" \ -F "sentence2=President Obama travelled to Kenya"
Document Search Task
curl -X POST https://koroai.neta.co.ke/model-hub/task-applications/predict/ \ -H "Authorization: Bearer <token>" \ -F "task_app_key=document_search" \ -F "model=273f9f25-12fe-4d30-b61a-111a9db687b1" \ -F "prompt=What is this document about?" \ -F "document=@/path/to/file.pdf"
Content Writing Task
curl -X POST https://koroai.neta.co.ke/model-hub/task-applications/predict/ \ -H "Authorization: Bearer <token>" \ -F "task_app_key=content_writing" \ -F "model=273f9f25-12fe-4d30-b61a-111a9db687b1" \ -F "prompt=Write a blog post about AI" \ -F "category=technology" \ -F "size_category=medium" \ -F "size=1"
FAQ Bot / Knowledge Base Assistant
curl -X POST https://koroai.neta.co.ke/model-hub/task-applications/predict/ \ -H "Authorization: Bearer <token>" \ -F "task_app_key=faq_bots" \ -F "model=273f9f25-12fe-4d30-b61a-111a9db687b1" \ -F "prompt=What is the refund policy?" \ -F "project=<project_id>" \
Example Response
{
"id": "8e92d66c-1a4e-4f3a-9274-fad33fa6a02d",
"model": "273f9f25-12fe-4d30-b61a-111a9db687b1",
"input_text": "Translate this to French",
"output_text": "Traduisez ceci en français",
"project": null,
"predicted_at": "2025-11-02T13:27:58.552Z",
"input_url": null,
"model_name": "Translation Model",
"task_key": "translation",
"input_type": "text"
}
Error Responses
{"error": "source_language and target_language are required for translation"}
{"error": "Document is required unless context text is provided."}
{"error": "Task application was not found"}
{"error": "Unexpected error occurred"}