Skip to main content
The agent deletion system allows you to delete existing agents. Deletion is implemented as a soft delete - the agent is marked as deleted but not physically removed from the database. This preserves data integrity, maintains audit trails, and allows for potential recovery.

​
API Endpoint

Endpoint: POST /api/agent/status Content-Type: application/json Authentication: Required (Token header: token or api_access_token)

​
Request Structure

{
  "agent_id": 123,
  "status": 2  // 2 = Deleted
}

​
cURL Example

curl -X POST "https://your-api-domain.com/api/agent/status" \
  -H "token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 123,
    "status": 2
  }'

​
Response

​
Success Response

Status Code: 200 OK 
{
  "message": "Agent Deleted Successfully",
  "data": {
    "id": 123,
    "name": "Agent Name",
    "status": 2
  }
}

​
Error Responses

​
422 - Validation Error

Status Code: 422 Unprocessable Entity 
{
  "error": true,
  "code": 422,
  "message": "Agent ID is missing",
  "data": {}
}
Common Error Messages:
  • "Agent ID is missing" - Required field agent_id is missing
  • "Status is missing" - Required field status is missing
  • "Agent ID is invalid" - Invalid agent ID format
  • "Agent not found" - Agent with provided ID does not exist or belongs to different workspace

​
401 - Authentication Error

Status Code: 401 Unauthorized 
{
  "error": true,
  "code": 401,
  "message": "Invalid Auth Key or Session Expired",
  "data": {}
}

​
500 - Server Error

Status Code: 500 Internal Server Error 
{
  "error": true,
  "code": 500,
  "message": "Internal server error",
  "data": {}
}

​
Error Codes

Status CodeError CodeDescription
200-Success
401AUTH_REQUIREDAuthentication required - Missing or invalid token
401AUTH_INVALIDInvalid authentication token or session expired
422VALIDATION_ERRORValidation failed - Check required fields and data format
422MISSING_FIELDRequired field missing
422INVALID_FORMATInvalid data format or type
422AGENT_NOT_FOUNDAgent with provided ID does not exist
500SERVER_ERRORInternal server error

​
Soft Delete Mechanism

​
What is Soft Delete?

Soft delete means the agent record remains in the database but is marked as deleted. The agent is not physically removed from the database. Benefits:
  • Data Preservation: Historical data is maintained
  • Audit Trail: Complete record of all agents and their history
  • Recovery: Deleted agents can be restored
  • Referential Integrity: Related records remain intact

​
How It Works

  1. Status Update: Agent STATUS field is set to 2 (deleted)
  2. Visibility: Deleted agents are automatically excluded from:
    • Agent lists
    • Agent searches
    • Agent selections
    • Public agent listings
  3. Data Preservation: All agent data and related records remain in the database

​
What Happens When an Agent is Deleted

​
1. Agent Record

  • Status is set to 2 (deleted)
  • Agent becomes invisible in queries
  • All agent data is preserved
All related records remain in the database:
  • Agent configuration
  • Knowledge base records
  • Tools and sub-agents
  • Calling numbers
  • Denied words
  • Dispositions
  • Guardrails
  • Metadata configurations
  • Change history

​
3. External Services Cleanup

Millis AI Platform:
  • Agent is deleted from Millis AI platform
  • Errors are logged but don’t prevent deletion
AI Service:
  • Knowledge base is deleted from AI service
  • Agent can no longer access knowledge base in AI service
Note: External service cleanup errors are logged but don’t prevent the agent from being marked as deleted in the database.

​
Agent Status Values

StatusValueDescription
Published1Agent is active and available for use
Deleted2Agent is soft-deleted (marked as deleted)
Unpublished3Agent is inactive but not deleted

​
Restoring Deleted Agents

Deleted agents can be restored by updating their status back to 1 (Published) or 3 (Unpublished).

​
Restore to Published

curl -X POST "https://your-api-domain.com/api/agent/status" \
  -H "token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 123,
    "status": 1
  }'

​
Restore to Unpublished

curl -X POST "https://your-api-domain.com/api/agent/status" \
  -H "token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 123,
    "status": 3
  }'
Note: When restoring an agent, external services (Millis AI, AI Service) are not automatically recreated. Manual intervention may be required for external services.

​
Important Notes

  • Deletion is a soft delete - agent remains in database with status 2
  • All related data (knowledge base, tools, configurations) is preserved
  • External services (Millis AI, AI Service) are cleaned up during deletion
  • Deleted agents are automatically excluded from all queries and listings
  • Deleted agents can be restored by updating status to 1 or 3
  • Complete audit trail is maintained for all deletions
  • External service cleanup errors don’t prevent deletion from completing
  • Knowledge base files remain in cloud storage (not automatically removed)