AI model management

Check if a model name exists

get

This endpoint allows authenticated users to verify if a specified AI model name already exists in the database. It performs a case-sensitive check and returns availability status to prevent naming conflicts when creating models.

---

Authentication

• Type: Bearer Token (API_KEY)

• Required: Yes

• Header: Authorization: Bearer <API_KEY>

• Dependency: Depends(APIKeyBearer())

---

Request Parameters

Parameter	Type	Required	Description
model_name	string	Yes	The model name to verify (3-50 chars, alphanumeric with hyphens/underscores)

---

Example Use Case

A user wants to create a new AI model named "finance-llm". Before submission, they use this endpoint to verify the name isn't already taken by another model in the system.

---

Example Request

GET /api/v2/model/training/check-name?model_name=finance-llm HTTP/1.1
Host: api.example.com
Authorization: Bearer <API_KEY>

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

model_namestringRequired

Model name to check

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

403

Error: Forbidden

application/json

422

Validation Error

application/json

get

/model/training/check-name

HTTPcURLJavaScriptPython

GET /api/v2/model/training/check-name?model_name=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get status and history of the last AI model created or updated

post

Get AI Model Training Status

This endpoint allows users to check the progress of their last AI model creation or update job. It retrieves the current status and provides a detailed history of all actions performed during the training process, enabling users to monitor their model's development in real-time.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To check training status on behalf of an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Returns the job status and detailed history of all actions performed during the process.
400	Bad Request - Various validation errors including user not found or job not found.
401	Unauthorized - Invalid or missing authentication token.
403	Forbidden - Insufficient permissions to access the job status.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following JobStatusSchema structure:

{
  "job_id": "job_abc123def456",
  "status_job": "IN_PROGRESS",
  "history": [
    "Repository cloned successfully",
    "Training data uploaded: 250 documents processed",
    "Data preprocessing completed",
    "Model initialization: Architecture configured",
    "Epoch 1/20 - Loss: 1.2345, Accuracy: 45.2%",
    "Epoch 5/20 - Loss: 0.8765, Accuracy: 68.7%",
    "Epoch 10/20 - Loss: 0.4567, Accuracy: 82.3%",
    "CONTRIBUTING.md guidelines applied"
  ]
}

---

Technical Process

The endpoint performs the following comprehensive operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. User Existence Check: Confirms the user exists in the database

4. Job Identification: Retrieves the last job ID from user profile data

5. Status Retrieval: Fetches the current job status from user data

6. History Collection: Gathers complete job history with action logs as strings

7. Response Formatting: Structures the response according to JobStatusSchema

---

Status Types

Status	Description
PENDING	Job is queued and waiting to start
IN_PROGRESS	Job is currently running
COMPLETED	Job finished successfully
ERROR	Job encountered an error

---

Common History Messages

The history array contains chronological strings describing each step of the process:

• Initialization: "Repository cloned successfully", "Environment setup completed"

• Data Processing: "Training data uploaded: X documents processed", "Data validation passed"

• Training Phase: "Epoch X/Y - Loss: X.XXXX, Accuracy: XX.X%", "Model checkpoint saved"

• Validation: "Validation accuracy: XX.X%", "Model performance metrics calculated"

• Completion: "Training completed successfully", "Model deployed to production"

• Documentation: "CONTRIBUTING.md guidelines applied", "Documentation generated"

---

Progress Monitoring Features

• Sequential logging: Chronological list of all actions performed

• Detailed descriptions: Specific actions and outcomes at each step

• Performance metrics: Training progress with loss and accuracy values

• Error reporting: Detailed error messages when failures occur

• Completion tracking: Clear indication of job progression through phases

---

Validation Checks

Check Type	Error Message
User not found	"User not found"
Acting user not authorized	"User {acting_user_email} is not in your teams"
Job not found	"Job not found"
Database error	"An error occurred while processing your request"

---

Example Use Cases

• Training Monitoring: Track real-time progress of AI model training jobs

• Debugging Assistance: Review detailed logs to identify issues in failed jobs

• Performance Analysis: Analyze training metrics and progression over time

• Status Dashboard: Display current job status with historical context

• Automated Notifications: Monitor job completion for follow-up actions

---

Example Request

POST /api/v2/model/training/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Responses

Active Training Job:

{
  "job_id": "job_abc123def456",
  "status_job": "IN_PROGRESS",
  "history": [
    "Repository cloned successfully",
    "Training data uploaded: 250 documents (1.2GB)",
    "Data preprocessing: Cleaning and tokenization completed",
    "Model architecture initialized with 50M parameters",
    "Epoch 1/20 - Loss: 2.3456, Accuracy: 32.1%",
    "Epoch 5/20 - Loss: 1.2345, Accuracy: 58.7%",
    "Epoch 10/20 - Loss: 0.8765, Accuracy: 72.3%",
    "CONTRIBUTING.md guidelines applied"
  ]
}

Completed Job:

{
  "job_id": "job_def456ghi789",
  "status_job": "COMPLETED",
  "history": [
    "Repository cloned successfully",
    "Training data uploaded: 500 documents (2.5GB)",
    "Data validation and preprocessing completed",
    "Model training started with 20 epochs",
    "Epoch 5/20 - Loss: 1.1234, Accuracy: 65.4%",
    "Epoch 10/20 - Loss: 0.6543, Accuracy: 78.9%",
    "Epoch 15/20 - Loss: 0.4321, Accuracy: 85.6%",
    "Epoch 20/20 - Loss: 0.3210, Accuracy: 89.2%",
    "Model validation completed: Accuracy: 87.5%",
    "Model optimized and compressed",
    "Deployed to production environment",
    "CONTRIBUTING.md guidelines applied",
    "Training completed successfully"
  ]
}

No Job Found:

{
  "job_id": null,
  "status_job": null,
  "history": null
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
User not found	400	"User not found"
Acting user not authorized	400	"User [email protected] is not in your teams"
Job not found	400	"Job not found"
Database error	400	"An error occurred while processing your request"

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Error: Forbidden

application/json

422

Validation Error

application/json

post

/model/training/status

HTTPcURLJavaScriptPython

POST /api/v2/model/training/status HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

{
  "history": [
    "Repository cloned!",
    "CONTRIBUTING.md"
  ],
  "job_id": "",
  "status_job": "IN_PROGRESS"
}

stop an asynchronous AI model creation or update

post

Stop AI Model Training Job

This endpoint allows users to cancel an ongoing AI model creation or update job. It provides immediate termination of asynchronous training processes with comprehensive cleanup and status updates.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To stop jobs on behalf of an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
job_id	string	Yes	Unique identifier of the job to cancel.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Job cancellation processed. Returns confirmation message.
400	Bad Request - Validation errors including permission issues.
401	Unauthorized - Invalid or missing authentication token.
403	Forbidden - Insufficient permissions to cancel the job.
404	Not Found - The specified job ID does not exist.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Job cancelled successfully",
  "job_id": "job_abc123def456"
}

---

Technical Process

The endpoint performs the following comprehensive operations:

1. Authentication & Authorization: Validates user credentials and external usage permissions

2. Job Existence Check: Verifies the specified job ID exists in the queue system

3. Job Status Validation: Checks if the job is still running and cancellable

4. Process Termination: Sends SIGKILL signal to the underlying process (if available)

5. Job Status Update: Marks the job as "stopped" in the queue system

6. Database Cleanup: Updates user status to "ERROR" to reflect cancellation

7. Confirmation Response: Returns success message with job ID

---

Cancellation Behavior

Job Status	Action Taken	Response
queued	Immediate cancellation	Success
started	Process termination + cleanup	Success
finished	No action (already completed)	Informational message
failed	No action (already failed)	Informational message
stopped	No action (already stopped)	Informational message

---

Process Termination

The endpoint employs a multi-layer termination approach:

1. Soft Cancellation: Attempts graceful job status update

2. Hard Termination: Sends SIGKILL to underlying process (if PID available)

3. Database Cleanup: Ensures consistent state across all systems

4. Status Synchronization: Updates both queue and user database records

---

Validation Checks

Check Type	Error Message
Job not found	"Job not found"
Acting user not authorized	"User {acting_user_email} is not in your teams"
Database update failure	Internal error (logged but not exposed to user)

---

Error Handling

The endpoint includes robust error handling with:

• Graceful Degradation: Continues cleanup even if some operations fail

• Comprehensive Logging: Detailed error logging for troubleshooting

• User-friendly Messages: Appropriate messages based on job state

• State Consistency: Ensures database and queue remain synchronized

---

Example Use Cases

• User-Initiated Cancellation: User wants to stop a long-running training job

• Resource Management: Free up system resources by terminating unnecessary jobs

• Error Recovery: Stop jobs that appear to be hanging or malfunctioning

• Plan Change: Cancel job after realizing subscription limitations

• Data Correction: Stop training to fix data issues before restarting

---

Example Request

POST /api/v2/model/training/cancel?job_id=job_abc123def456&[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Responses

Successful Cancellation:

{
  "detail": "Job cancelled successfully",
  "job_id": "job_abc123def456"
}

Job Already Completed:

{
  "detail": "Job already completed or failed",
  "job_id": "job_abc123def456"
}

Job Not Found:

{
  "status": 404,
  "message": "Job not found"
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Job not found	404	"Job not found"
Acting user not authorized	400	"User [email protected] is not in your teams"
Internal system error	400	Internal server error (logged)

---

Security Considerations

• Only job owners can cancel their own jobs

• External users require explicit permission configuration

• Process termination is restricted to owned processes

• Comprehensive audit logging of cancellation events

---

Performance Impact

• Immediate termination frees up system resources

• Minimal overhead for cancellation operations

• Efficient database updates without full transaction locks

• Scalable for high-volume cancellation requests

---

Recovery Options

After cancellation, users can:

1. Restart Training: Initiate a new training job with corrected parameters

2. Review Logs: Examine job history to understand why cancellation was needed

3. Contact Support: Get assistance if cancellations are frequent or unexpected

4. Monitor Resources: Check system status before starting new jobs

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

job_idanyRequired

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

403

Error: Forbidden

application/json

422

Validation Error

application/json

post

/model/training/cancel

HTTPcURLJavaScriptPython

POST /api/v2/model/training/cancel?job_id=null HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

No content

Generate a new asynchronous AI model

post

Generate New Asynchronous AI Model

This endpoint allows users to create and train a new AI model asynchronously using various data sources including files, URLs, repositories, and external platforms. It handles comprehensive validation, data processing, and queues the training job for background execution.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To generate models on behalf of an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").
Content-Type	string	Yes	Must be multipart/form-data for file uploads and form data.

---

Form Parameters

Basic Model Configuration

Parameter	Type	Required	Description
model_name	string	Yes	Unique name for the AI model
type_files	string	Yes	Type of data: unstructured
type_llm	LLMEnum	Yes	AI model type to use for training
language	ModelLanguageEnum	Yes	Primary language for the model
secret	string	No	Encryption passphrase for Enterprise users

Data Sources (At least one required)

Parameter	Type	Required	Description
user_files	List[UploadFile]	No	Unstructured files for training
url	string	No	Website URL to crawl for data
repo_url	string	No	GitHub repository URL
azure_organization_url	string	No	Azure DevOps organization URL
jira_organization_url	string	No	Jira instance URL
s3_access_point_arn	string	No	AWS S3 access point ARN
notion_database_id	string	No	Notion database ID
confluence_organization_url	string	No	Confluence instance URL
gdrive_prefix	string	No	Google Drive folder prefix
onedrive_prefix	string	No	OneDrive folder prefix
sharepoint_prefix	string	No	SharePoint folder prefix
hubspot_pat	string	No	HubSpot personal access token
servicenow_instance_url	string	No	ServiceNow instance URL

Repository Configuration (GitHub)

Parameter	Type	Required	Description
repository_type	RepositoryTypeEnum	No	Type of repository: GitHub or Azure DevOps
branch_name	string	No	Repository branch name
is_private_repo	boolean	No	Whether repository is private
gitHub_personal_access_token	string	No	GitHub PAT for private repos

Azure DevOps Configuration

Parameter	Type	Required	Description
azure_project_name	string	No	Azure DevOps project name
azure_repository_name	string	No	Azure repository name
azure_branch_or_tag_name	string	No	Branch or tag name
azure_personal_access_token	string	No	Azure PAT

Jira Configuration

Parameter	Type	Required	Description
jira_project_key	string	No	Jira project key
jira_items	int	No	Number of items to fetch
jira_parameters	string	No	JQL query parameters
jira_personal_access_token	string	No	Jira PAT
jira_mail	string	No	Jira user email

AWS S3 Configuration

Parameter	Type	Required	Description
s3_prefix	string	No	S3 path prefix
s3_items	int	No	Number of items to fetch
s3_access_key	string	No	AWS access key
s3_secret_key	string	No	AWS secret key
s3_region	string	No	AWS region

Notion Configuration

Parameter	Type	Required	Description
notion_items	int	No	Number of items to fetch
notion_access_token	string	No	Notion integration token

Confluence Configuration

Parameter	Type	Required	Description
confluence_space_key	string	No	Confluence space key
confluence_items	int	No	Number of items to fetch
confluence_parameters	string	No	Search parameters
confluence_personal_access_token	string	No	Confluence PAT
confluence_mail	string	No	Confluence user email

Cloud Storage Configuration

Parameter	Type	Required	Description
onedrive_items	int	No	OneDrive items limit
sharepoint_site_url	string	No	SharePoint site URL
sharepoint_library_name	string	No	SharePoint library name
sharepoint_items	int	No	SharePoint items limit
gdrive_items	int	No	Google Drive items limit

HubSpot Configuration

Parameter	Type	Required	Description
hubspot_items	int	No	HubSpot items limit
hubspot_parameters	string	No	HubSpot query parameters

ServiceNow Configuration

Parameter	Type	Required	Description
servicenow_table	string	No	ServiceNow table name
servicenow_items	int	No	Number of items to fetch
servicenow_parameters	string	No	Query parameters
servicenow_personal_access_token	string	No	ServiceNow PAT

Web Crawling Configuration

Parameter	Type	Required	Description
crawling_mode	CrawlingModeEnum	No	Crawling strategy
max_pages	int	No	Maximum pages to crawl (default: 300)
exclusion_patterns_input	string	No	URL patterns to exclude
specific_urls_input	string	No	Specific URLs to include

Model Behavior Configuration

Parameter	Type	Required	Description
personality	PersonalityTypeEnum	Yes	AI personality type
tone	ToneTypeEnum	Yes	Response tone style
detail_level	DetailLevelEnum	Yes	Level of response detail
response_language	ResponseLanguageEnum	Yes	Output language for responses
allow_public_info	NoYesEnum	Yes	Allow public information usage
show_references	NoYesEnum	Yes	Show source references
description	string	No	Model description

Prompt Engineering

Parameter	Type	Required	Description
first_message	string	No	Initial greeting message
custom_prompt	string	No	Custom instruction prompt
prompt1 to prompt5	string	No	Additional prompt templates

Data Processing

Parameter	Type	Required	Description
separator	SeparatorEnum	Yes	Text segmentation separator
chunk_size	int	Yes	Text chunk size (default: 1500)
chunk_overlap	int	Yes	Chunk overlap size (default: 300)

Integration Options

Parameter	Type	Required	Description
collect_user_info	boolean	No	Enable user information collection
collect_email	boolean	No	Collect email addresses
collect_phone	boolean	No	Collect phone numbers
hubspot_api_key	string	No	HubSpot API key for CRM integration
n8n_api_key	string	No	n8n workflow automation key
zoho_key	boolean	No	Enable Zoho integration
imageopt	boolean	No	Enable image optimization

External User Support

Parameter	Type	Required	Description
acting_user_email	string	No	Email of user acting on owner's behalf

---

Responses

Status Code	Description
200	Success - Model training job queued successfully. Returns job ID for tracking.
400	Bad Request - Validation errors including missing data sources, invalid parameters, or plan limitations.
401	Unauthorized - Invalid or missing authentication token.
403	Forbidden - Insufficient permissions or subscription limitations.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Model creation in progress",
  "job_id": "job_abc123def456"
}

---

Technical Process

The endpoint performs the following comprehensive operations:

1. Authentication & Authorization: Validates user credentials and external usage permissions

2. Data Source Validation: Ensures at least one data source is provided

3. Job Status Check: Verifies no other model is currently being trained for the user

4. Model Name Validation: Checks for unique and valid model names

5. Subscription Validation: Verifies user has appropriate plan for requested features

6. Integration Validation: Validates all required parameters for external integrations

7. File Processing: Handles file uploads and storage

8. Parameter Validation: Validates text processing parameters

9. Job Queuing: Enqueues the training job for asynchronous processing

10. Status Tracking: Initializes job tracking and history

---

Validation Checks

Check Type	Error Message
No data source provided	"Please provide at least one data source"
Model already in progress	"A model is already in progress"
Invalid model name	"Invalid model name"
Duplicate model name	"Model name already exists"
Plan upgrade required	"Upgrade your plan to access this feature"
Enterprise required for Understand AI	"Enterprise plan required for Understand AI"
Secret required for encryption	"Secret required for Enterprise users"
Missing repository parameters	Various specific missing parameter errors
Invalid chunk parameters	"Invalid chunk size" or "Invalid chunk overlap"

---

Subscription Requirements

Feature	Required Plan
Understand AI LLM	Enterprise
Encryption	Enterprise
Advanced integrations	Premium or Enterprise
Increased limits	Higher tiers

---

Example Use Cases

• Document-based AI: Train on company documents and manuals

• Website Knowledge Base: Create AI from website content crawling

• Code Assistant: Train on GitHub repositories for code understanding

• Customer Support: Build AI from helpdesk tickets (Jira, ServiceNow)

• Enterprise Knowledge: Integrate Confluence, SharePoint, and internal docs

• Structured Data Analysis: Train on CSV/JSON data for data interpretation

---

Example Requests

Basic File Upload:

POST /api/v2/model/training HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: multipart/form-data

model_name=MyAssistant&type_files=unstructured&type_llm=GPT-4&language=en&personality=professional&tone=friendly&detail_level=detailed&response_language=en&allow_public_info=yes&show_references=yes&separator=Period&chunk_size=1500&chunk_overlap=300

Website Crawling:

POST /api/v2/model/training HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: multipart/form-data

model_name=WebExpert&type_files=unstructured&type_llm=Understand AI&url=https://company.com/docs&max_pages=100&language=en&personality=helpful&tone=professional&secret=my_encryption_key

GitHub Repository:

POST /api/v2/model/training HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: multipart/form-data

model_name=CodeAssistant&type_files=unstructured&type_llm=GPT-4&repository_type=GitHub&repo_url=https://github.com/company/repo&is_private_repo=true&gitHub_personal_access_token=ghp_abc123&language=en&personality=technical

---

Example Response

{
  "detail": "Model creation in progress",
  "job_id": "job_abc123def456"
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
No data sources	400	"Please provide at least one data source"
Model in progress	400	"A model is already in progress"
Invalid model name	400	"Invalid model name"
Plan upgrade required	400	"Upgrade your plan to access this feature"
Missing required parameters	400	Various specific parameter errors
Database error	400	"An error occurred while processing your request"

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

multipart/form-data

secretstringOptional

model_namestringRequired

user_filesany ofOptionalDefault: []

string · binary[]Optional

or

nullOptional

user_structured_filesany ofOptionalDefault: []

string · binary[]Optional

or

nullOptional

type_filesstringRequired

urlstringOptional

crawling_modestring · enumOptionalPossible values:

max_pagesintegerOptionalDefault: 300

exclusion_patterns_inputstringOptional

specific_urls_inputstringOptional

type_llmstring · enumRequiredPossible values:

first_messagestringOptional

custom_promptstringOptional

prompt1stringOptional

prompt2stringOptional

prompt3stringOptional

prompt4stringOptional

prompt5stringOptional

collect_user_infobooleanOptional

collect_emailbooleanOptional

collect_phonebooleanOptional

hubspot_api_keystringOptional

repository_typestring · enumOptionalPossible values:

repo_urlstringOptional

branch_namestringOptional

is_private_repobooleanOptional

gitHub_personal_access_tokenstringOptional

azure_organization_urlstringOptional

azure_project_namestringOptional

azure_repository_namestringOptional

azure_branch_or_tag_namestringOptional

azure_personal_access_tokenstringOptional

jira_organization_urlstringOptional

jira_project_keystringOptional

jira_itemsintegerOptional

jira_parametersstringOptional

jira_personal_access_tokenstringOptional

jira_mailstringOptional

s3_access_point_arnstringOptional

s3_prefixstringOptional

s3_itemsintegerOptional

s3_access_keystringOptional

s3_secret_keystringOptional

s3_regionstringOptional

onedrive_itemsintegerOptional

onedrive_prefixstringOptional

sharepoint_itemsintegerOptional

sharepoint_site_urlstringOptional

sharepoint_library_namestringOptional

sharepoint_prefixstringOptional

notion_database_idstringOptional

notion_itemsintegerOptional

notion_access_tokenstringOptional

confluence_organization_urlstringOptional

confluence_space_keystringOptional

confluence_itemsintegerOptional

confluence_parametersstringOptional

confluence_personal_access_tokenstringOptional

confluence_mailstringOptional

gdrive_prefixstringOptional

gdrive_itemsintegerOptional

hubspot_patstringOptional

hubspot_itemsintegerOptional

hubspot_parametersstringOptional

servicenow_instance_urlstringOptional

servicenow_itemsintegerOptional

servicenow_tablestringOptional

servicenow_parametersstringOptional

servicenow_personal_access_tokenstringOptional

zoho_keybooleanOptionalDefault: false

imageoptbooleanOptionalDefault: false

languagestring · enumRequiredPossible values:

personalitystring · enumRequiredPossible values:

tonestring · enumRequiredPossible values:

detail_levelstring · enumRequiredPossible values:

allow_public_infostring · enumRequiredPossible values:

response_languagestring · enumRequiredPossible values:

show_referencesstring · enumRequiredPossible values:

descriptionstringOptionalDefault: ""

n8n_api_keystringOptional

separatorstring · enumRequiredPossible values:

chunk_sizeintegerOptionalDefault: 1500

chunk_overlapintegerOptionalDefault: 300

acting_user_emailstringOptional

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

403

Error: Forbidden

application/json

422

Validation Error

application/json

post

/model/training

HTTPcURLJavaScriptPython

POST /api/v2/model/training HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: multipart/form-data
Accept: */*
Content-Length: 2095

{
  "secret": "text",
  "model_name": "text",
  "user_files": [
    "binary"
  ],
  "user_structured_files": [
    "binary"
  ],
  "type_files": "text",
  "url": "text",
  "crawling_mode": "Crawl Entire Site",
  "max_pages": 300,
  "exclusion_patterns_input": "text",
  "specific_urls_input": "text",
  "type_llm": "🇺🇸 OpenAI",
  "first_message": "text",
  "custom_prompt": "text",
  "prompt1": "text",
  "prompt2": "text",
  "prompt3": "text",
  "prompt4": "text",
  "prompt5": "text",
  "collect_user_info": true,
  "collect_email": true,
  "collect_phone": true,
  "hubspot_api_key": "text",
  "repository_type": "",
  "repo_url": "text",
  "branch_name": "text",
  "is_private_repo": true,
  "gitHub_personal_access_token": "text",
  "azure_organization_url": "text",
  "azure_project_name": "text",
  "azure_repository_name": "text",
  "azure_branch_or_tag_name": "text",
  "azure_personal_access_token": "text",
  "jira_organization_url": "text",
  "jira_project_key": "text",
  "jira_items": 1,
  "jira_parameters": "text",
  "jira_personal_access_token": "text",
  "jira_mail": "text",
  "s3_access_point_arn": "text",
  "s3_prefix": "text",
  "s3_items": 1,
  "s3_access_key": "text",
  "s3_secret_key": "text",
  "s3_region": "text",
  "onedrive_items": 1,
  "onedrive_prefix": "text",
  "sharepoint_items": 1,
  "sharepoint_site_url": "text",
  "sharepoint_library_name": "text",
  "sharepoint_prefix": "text",
  "notion_database_id": "text",
  "notion_items": 1,
  "notion_access_token": "text",
  "confluence_organization_url": "text",
  "confluence_space_key": "text",
  "confluence_items": 1,
  "confluence_parameters": "text",
  "confluence_personal_access_token": "text",
  "confluence_mail": "text",
  "gdrive_prefix": "text",
  "gdrive_items": 1,
  "hubspot_pat": "text",
  "hubspot_items": 1,
  "hubspot_parameters": "text",
  "servicenow_instance_url": "text",
  "servicenow_items": 1,
  "servicenow_table": "text",
  "servicenow_parameters": "text",
  "servicenow_personal_access_token": "text",
  "zoho_key": false,
  "imageopt": false,
  "language": "🇺🇸 English",
  "personality": "Professional",
  "tone": "Formal",
  "detail_level": "Adaptive Detail Level",
  "allow_public_info": "No",
  "response_language": "User Chosen Language",
  "show_references": "No",
  "description": "",
  "n8n_api_key": "text",
  "separator": "Newline",
  "chunk_size": 1500,
  "chunk_overlap": 300,
  "acting_user_email": "text"
}

No content

Update an existing AI model asynchronously

put

Update Existing AI Model Asynchronously

This endpoint allows users to update an existing AI model with new data, parameters, or configurations. It supports both simple parameter updates and comprehensive retraining with new data sources, handling the process asynchronously with detailed validation and job tracking.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To update models on behalf of an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").
Content-Type	string	Yes	Must be multipart/form-data for file uploads and form data.

---

Path Parameters

Parameter Name	Type	Required	Description
model_id	string	Yes	Unique identifier of the model to update.

---

Form Parameters

Basic Model Configuration

Parameter	Type	Required	Description
model_name	string	Yes	Updated name for the AI model
type_files	string	Yes	Type of data: unstructured
type_llm	LLMEnum	Yes	AI model type (immutable after creation)
language	ModelLanguageEnum	Yes	Primary language for the model
secret	string	No	Encryption passphrase for Enterprise users
enhance_existing	boolean	No	Enhance existing data instead of replacing
autoupdate	boolean	No	Enable automatic periodic updates
updatetime	int	No	Update frequency in hours (if autoupdate enabled)

Data Sources (Optional - for retraining)

Parameter	Type	Required	Description
user_files	List[UploadFile]	No	New unstructured files for training
&	List[UploadFile]	No	New structured files (CSV, JSON, etc.)
url	string	No	New website URL to crawl for data
repo_url	string	No	New GitHub repository URL

Repository & Integration Updates

Same extensive list of parameters as the create endpoint for GitHub, Azure DevOps, Jira, Confluence, AWS S3, Notion, SharePoint, OneDrive, Google Drive, HubSpot, ServiceNow integrations

Model Behavior Updates

Parameter	Type	Required	Description
personality	PersonalityTypeEnum	Yes	Updated AI personality type
tone	ToneTypeEnum	Yes	Updated response tone style
detail_level	DetailLevelEnum	Yes	Updated level of response detail
response_language	ResponseLanguageEnum	Yes	Updated output language for responses
allow_public_info	NoYesEnum	Yes	Updated public information usage setting
show_references	NoYesEnum	Yes	Updated source references setting
description	string	No	Updated model description

Prompt Engineering Updates

Parameter	Type	Required	Description
first_message	string	No	Updated initial greeting message
custom_prompt	string	No	Updated custom instruction prompt
prompt1 to prompt5	string	No	Updated prompt templates

Data Processing Updates

Parameter	Type	Required	Description
separator	SeparatorEnum	Yes	Updated text segmentation separator
chunk_size	int	Yes	Updated text chunk size
chunk_overlap	int	Yes	Updated chunk overlap size

Integration Updates

Parameter	Type	Required	Description
collect_user_info	boolean	No	Updated user information collection setting
collect_email	boolean	No	Updated email collection setting
collect_phone	boolean	No	Updated phone collection setting
hubspot_api_key	string	No	Updated HubSpot API key
n8n_api_key	string	No	Updated n8n workflow automation key
zoho_key	boolean	No	Updated Zoho integration setting

External User Support

Parameter	Type	Required	Description
acting_user_email	string	No	Email of user acting on owner's behalf

---

Responses

Status Code	Description
200	Success - Model update processed. Returns immediate success for parameter updates or job ID for retraining.
400	Bad Request - Validation errors including model not found, immutable field changes, or plan limitations.
401	Unauthorized - Invalid or missing authentication token.
403	Forbidden - Insufficient permissions or subscription limitations.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

For parameter updates (no new data):

{
  "detail": "Model parameters updated successfully"
}

For retraining with new data:

{
  "detail": "Model update in progress",
  "job_id": "job_abc123def456"
}

---

Technical Process

The endpoint performs the following comprehensive operations:

1. Authentication & Authorization: Validates user credentials and external usage permissions

2. Job Status Check: Ensures no other model is currently being updated for the user

3. Model Existence Verification: Confirms the specified model exists and belongs to the user

4. Immutable Field Validation: Prevents changes to immutable fields like AI model type

5. Update Type Determination: Differentiates between parameter updates and retraining

6. Data Source Validation: Validates new data sources if provided

7. Subscription Validation: Verifies user has appropriate plan for requested features

8. Integration Validation: Validates all required parameters for external integrations

9. File Processing: Handles new file uploads and storage

10. Job Queuing: Enqueues retraining job for asynchronous processing when needed

11. Immediate Updates: Directly updates parameters in database when no new data provided

---

Update Types

1. Parameter Updates

• Updates model metadata and configuration only

• No retraining occurs

• Immediate database update

• Returns instant success response

2. Retraining with New Data

• Adds new data sources to existing model

• Queues asynchronous training job

• Returns job ID for progress tracking

• Supports both enhancement and replacement modes

---

Immutable Fields

The following fields cannot be changed after model creation:

• type_llm (AI model type)

• Base model architecture and type

---

Validation Checks

Check Type	Error Message
Model not found	"Model not found"
Model already in progress	"A model is already in progress"
Immutable field change	"AI model type cannot be changed"
Plan upgrade required	"Upgrade your plan to access this feature"
Enterprise required for Understand AI	"Enterprise plan required for Understand AI"
Secret required for encryption	"Secret required for Enterprise users"
Missing integration parameters	Various specific missing parameter errors

---

Example Use Cases

• Model Refinement: Update personality, tone, or response behavior

• Knowledge Expansion: Add new documents or data sources to existing model

• Bug Fixing: Correct model behavior by adding corrective data

• Integration Updates: Modify CRM or automation integrations

• Scheduled Updates: Enable automatic periodic knowledge updates

• Security Enhancement: Update encryption or access controls

---

Example Requests

Simple Parameter Update:

PUT /api/v2/model/model_abc123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: multipart/form-data

model_name=UpdatedAssistant&type_files=unstructured&type_llm=GPT-4&language=en&personality=technical&tone=professional&detail_level=detailed&response_language=en&allow_public_info=no&show_references=yes&separator=Period&chunk_size=2000&chunk_overlap=400

Retraining with New Files:

PUT /api/v2/model/model_abc123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: multipart/form-data

model_name=EnhancedAssistant&type_files=unstructured&type_llm=GPT-4&language=en&personality=helpful&enhance_existing=true&secret=my_encryption_key

Automatic Updates:

PUT /api/v2/model/model_abc123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: multipart/form-data

model_name=AutoUpdatedAssistant&type_files=unstructured&type_llm=GPT-4&autoupdate=true&updatetime=24&url=https://company.com/news

---

Example Responses

Parameter Update Success:

{
  "detail": "Model parameters updated successfully"
}

Retraining Started:

{
  "detail": "Model update in progress",
  "job_id": "job_abc123def456"
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Model not found	400	"Model not found"
Model in progress	400	"A model is already in progress"
Immutable field change	400	"AI model type cannot be changed"
Plan upgrade required	400	"Upgrade your plan to access this feature"
Missing required parameters	400	Various specific parameter errors

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

model_idstringRequired

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

multipart/form-data

model_namestringRequired

secretstringOptional

user_filesany ofOptionalDefault: []

string · binary[]Optional

or

nullOptional

user_structured_filesany ofOptionalDefault: []

string · binary[]Optional

or

nullOptional

type_filesstringRequired

urlstringOptional

crawling_modeany ofRequired

string · enumOptionalPossible values:

or

nullOptional

max_pagesintegerOptionalDefault: 300

exclusion_patterns_inputstringOptional

specific_urls_inputstringOptional

type_llmstring · enumRequiredPossible values:

first_messagestringOptional

custom_promptstringOptional

prompt1stringOptional

prompt2stringOptional

prompt3stringOptional

prompt4stringOptional

prompt5stringOptional

collect_user_infobooleanOptional

collect_emailbooleanOptional

collect_phonebooleanOptional

hubspot_api_keystringOptional

repository_typestring · enumOptionalPossible values:

repo_urlstringOptional

branch_namestringOptional

is_private_repobooleanOptional

gitHub_personal_access_tokenstringOptional

azure_organization_urlstringOptional

azure_project_namestringOptional

azure_repository_namestringOptional

azure_branch_or_tag_namestringOptional

azure_personal_access_tokenstringOptional

jira_organization_urlstringOptional

jira_project_keystringOptional

jira_itemsintegerOptional

jira_parametersstringOptional

jira_personal_access_tokenstringOptional

jira_mailstringOptional

confluence_organization_urlstringOptional

confluence_space_keystringOptional

confluence_itemsintegerOptional

confluence_parametersstringOptional

confluence_personal_access_tokenstringOptional

confluence_mailstringOptional

s3_access_point_arnstringOptional

s3_prefixstringOptional

s3_itemsintegerOptional

s3_access_keystringOptional

s3_secret_keystringOptional

s3_regionstringOptional

onedrive_itemsintegerOptional

onedrive_prefixstringOptional

sharepoint_itemsintegerOptional

sharepoint_site_urlstringOptional

sharepoint_library_namestringOptional

sharepoint_prefixstringOptional

notion_database_idstringOptional

notion_itemsintegerOptional

notion_access_tokenstringOptional

gdrive_prefixstringOptional

gdrive_itemsintegerOptional

hubspot_patstringOptional

hubspot_itemsintegerOptional

servicenow_instance_urlstringOptional

servicenow_itemsintegerOptional

servicenow_tablestringOptional

servicenow_parametersstringOptional

servicenow_personal_access_tokenstringOptional

hubspot_parametersstringOptional

zoho_keybooleanOptionalDefault: false

imageoptbooleanOptionalDefault: false

languagestring · enumRequiredPossible values:

personalitystring · enumRequiredPossible values:

tonestring · enumRequiredPossible values:

detail_levelstring · enumRequiredPossible values:

allow_public_infostring · enumRequiredPossible values:

response_languagestring · enumRequiredPossible values:

show_referencesstring · enumRequiredPossible values:

descriptionstringOptionalDefault: ""

n8n_api_keystringOptional

separatorstring · enumRequiredPossible values:

chunk_sizeintegerOptionalDefault: 1500

chunk_overlapintegerOptionalDefault: 300

enhance_existingbooleanOptionalDefault: false

timestampstring · date-timeOptional

autoupdatebooleanOptionalDefault: false

updatetimeintegerOptional

acting_user_emailstringOptional

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

403

Error: Forbidden

application/json

422

Validation Error

application/json

put

/model/{model_id}

HTTPcURLJavaScriptPython

PUT /api/v2/model/{model_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: multipart/form-data
Accept: */*
Content-Length: 2193

{
  "model_name": "text",
  "secret": "text",
  "user_files": [
    "binary"
  ],
  "user_structured_files": [
    "binary"
  ],
  "type_files": "text",
  "url": "text",
  "crawling_mode": "Crawl Entire Site",
  "max_pages": 300,
  "exclusion_patterns_input": "text",
  "specific_urls_input": "text",
  "type_llm": "🇺🇸 OpenAI",
  "first_message": "text",
  "custom_prompt": "text",
  "prompt1": "text",
  "prompt2": "text",
  "prompt3": "text",
  "prompt4": "text",
  "prompt5": "text",
  "collect_user_info": true,
  "collect_email": true,
  "collect_phone": true,
  "hubspot_api_key": "text",
  "repository_type": "",
  "repo_url": "text",
  "branch_name": "text",
  "is_private_repo": true,
  "gitHub_personal_access_token": "text",
  "azure_organization_url": "text",
  "azure_project_name": "text",
  "azure_repository_name": "text",
  "azure_branch_or_tag_name": "text",
  "azure_personal_access_token": "text",
  "jira_organization_url": "text",
  "jira_project_key": "text",
  "jira_items": 1,
  "jira_parameters": "text",
  "jira_personal_access_token": "text",
  "jira_mail": "text",
  "confluence_organization_url": "text",
  "confluence_space_key": "text",
  "confluence_items": 1,
  "confluence_parameters": "text",
  "confluence_personal_access_token": "text",
  "confluence_mail": "text",
  "s3_access_point_arn": "text",
  "s3_prefix": "text",
  "s3_items": 1,
  "s3_access_key": "text",
  "s3_secret_key": "text",
  "s3_region": "text",
  "onedrive_items": 1,
  "onedrive_prefix": "text",
  "sharepoint_items": 1,
  "sharepoint_site_url": "text",
  "sharepoint_library_name": "text",
  "sharepoint_prefix": "text",
  "notion_database_id": "text",
  "notion_items": 1,
  "notion_access_token": "text",
  "gdrive_prefix": "text",
  "gdrive_items": 1,
  "hubspot_pat": "text",
  "hubspot_items": 1,
  "servicenow_instance_url": "text",
  "servicenow_items": 1,
  "servicenow_table": "text",
  "servicenow_parameters": "text",
  "servicenow_personal_access_token": "text",
  "hubspot_parameters": "text",
  "zoho_key": false,
  "imageopt": false,
  "language": "🇺🇸 English",
  "personality": "Professional",
  "tone": "Formal",
  "detail_level": "Adaptive Detail Level",
  "allow_public_info": "No",
  "response_language": "User Chosen Language",
  "show_references": "No",
  "description": "",
  "n8n_api_key": "text",
  "separator": "Newline",
  "chunk_size": 1500,
  "chunk_overlap": 300,
  "enhance_existing": false,
  "timestamp": "2026-01-27T22:33:36.295Z",
  "autoupdate": false,
  "updatetime": 1,
  "acting_user_email": "text"
}

No content