Delete Agent

DELETE /api/v1/agents/{agentId}

Delete an agent by setting its status to inactive. This is a soft delete operation that preserves all agent data including conversation history, configuration, and metrics.

Endpoint

DELETE https://v2.heppu.ai/api/v1/agents/{agentId}

Authentication

Requires API key authentication via x-api-key or Authorization header.

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	Agent UUID to delete

Response

Returns a confirmation of the deletion.

Success Response (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "deleted": true
  },
  "message": "Agent deleted successfully"
}

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": 401
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "message": "Agent not found",
    "code": 404
  }
}

Examples

cURL

# Delete an agent
curl -X DELETE "https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

# Delete with Authorization header
curl -X DELETE "https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

// Using fetch
const deleteAgent = async (agentId) => {
  const response = await fetch(
    `https://v2.heppu.ai/api/v1/agents/${agentId}`,
    {
      method: 'DELETE',
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  const result = await response.json();
  return result.data;
};

// Usage
await deleteAgent('550e8400-e29b-41d4-a716-446655440000');
console.log('Agent deleted successfully');

// Using axios
const axios = require('axios');

const response = await axios.delete(
  'https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000',
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);

console.log(response.data.message);

Python

import requests

def delete_agent(agent_id):
    response = requests.delete(
        f'https://v2.heppu.ai/api/v1/agents/{agent_id}',
        headers={'x-api-key': 'YOUR_API_KEY'}
    )

    if response.status_code != 200:
        error = response.json()
        raise Exception(error['error']['message'])

    return response.json()['data']

# Usage
agent_id = '550e8400-e29b-41d4-a716-446655440000'
result = delete_agent(agent_id)
print(f"Agent {result['id']} deleted successfully")

# With error handling
try:
    delete_agent(agent_id)
    print("Agent deleted successfully")
except Exception as e:
    print(f"Failed to delete agent: {e}")

Node.js (with TypeScript)

interface DeleteAgentResponse {
  id: string;
  deleted: boolean;
}

async function deleteAgent(agentId: string): Promise<DeleteAgentResponse> {
  const response = await fetch(
    `https://v2.heppu.ai/api/v1/agents/${agentId}`,
    {
      method: 'DELETE',
      headers: {
        'x-api-key': process.env.HEPPU_API_KEY!,
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  const result = await response.json();
  return result.data;
}

// Usage
const result = await deleteAgent('550e8400-e29b-41d4-a716-446655440000');
console.log(`Agent ${result.id} deleted: ${result.deleted}`);

// With error handling and confirmation
async function safeDeleteAgent(agentId: string): Promise<boolean> {
  try {
    const result = await deleteAgent(agentId);
    return result.deleted;
  } catch (error) {
    console.error('Failed to delete agent:', error);
    return false;
  }
}

const success = await safeDeleteAgent('550e8400-e29b-41d4-a716-446655440000');
if (success) {
  console.log('Agent deleted successfully');
} else {
  console.log('Failed to delete agent');
}

Soft Delete Behavior

This endpoint performs a soft delete operation, which means:

Agent status is set to inactive
- The agent will no longer accept new calls or conversations
- Existing conversations are preserved
Data is preserved
- All conversation history remains accessible
- Configuration and settings are retained
- Metrics and analytics data is preserved
- Phone number assignments (for voice agents) remain in the database
Agent remains queryable
- The agent can still be retrieved via GET endpoint
- It will appear in list results with status: "inactive"
- The updatedAt timestamp is updated to the deletion time
Can be reactivated
- Update the agent's status back to active to restore functionality
- All configuration and data will be intact

Reactivating a Deleted Agent

Since deletion is soft, you can reactivate an agent by updating its status:

// Reactivate a deleted agent
await updateAgent(agentId, {
  status: 'active'
});

# Reactivate using update endpoint
update_agent(agent_id, {
    'status': 'active'
})

Common Use Cases

Delete with Confirmation

async function deleteAgentWithConfirmation(agentId) {
  // Get agent details first
  const agent = await getAgent(agentId);

  console.log(`Are you sure you want to delete "${agent.name}"?`);
  // ... confirmation logic ...

  // Delete the agent
  await deleteAgent(agentId);
  console.log('Agent deleted successfully');
}

Bulk Delete

async function deleteMultipleAgents(agentIds) {
  const results = await Promise.allSettled(
    agentIds.map(id => deleteAgent(id))
  );

  const succeeded = results.filter(r => r.status === 'fulfilled').length;
  const failed = results.filter(r => r.status === 'rejected').length;

  console.log(`Deleted: ${succeeded}, Failed: ${failed}`);
  return { succeeded, failed };
}

// Usage
await deleteMultipleAgents([
  '550e8400-e29b-41d4-a716-446655440000',
  '660e8400-e29b-41d4-a716-446655440001',
]);

Delete Inactive Agents

async function deleteInactiveAgents() {
  // Get all agents
  const response = await fetch(
    'https://v2.heppu.ai/api/v1/agents?status=inactive',
    {
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    }
  );

  const result = await response.json();
  const inactiveAgents = result.data.agents;

  // Delete each inactive agent
  for (const agent of inactiveAgents) {
    await deleteAgent(agent.id);
    console.log(`Deleted agent: ${agent.name}`);
  }

  console.log(`Deleted ${inactiveAgents.length} inactive agents`);
}

Archive Agent Before Deletion

async function archiveAndDelete(agentId) {
  // Get agent details
  const agent = await getAgent(agentId);

  // Save to archive (your custom logic)
  await saveToArchive(agent);

  // Delete the agent
  await deleteAgent(agentId);

  console.log(`Agent ${agent.name} archived and deleted`);
}

Voice Agents

Phone numbers: Remain assigned in the database but stop routing calls
Ongoing calls: Continue until completion, then new calls are rejected
Call history: Fully preserved and accessible

Chat Agents

Widget: Stops responding to new messages
Ongoing conversations: Continue but new conversations cannot start
Conversation history: Fully preserved and accessible

Both Agent Types

Tools: Associations remain in database
Metrics: All historical metrics are preserved
API access: Agent can still be queried but won't process new requests

Important Notes

This is a soft delete - data is not permanently removed
Agent must belong to your organization to delete
Deletion is immediate and affects new requests right away
Ongoing conversations may continue briefly before being terminated
The operation is idempotent - deleting an already deleted agent succeeds
To permanently delete data, contact support
The updatedAt timestamp is set to the deletion time
Deleted agents count toward your organization's total agent count
Reactivation is possible at any time via the update endpoint

Permanent Deletion

If you need to permanently delete agent data:

Contact support with the agent ID
Provide a reason for permanent deletion
Confirm understanding that this action is irreversible
Support will process the permanent deletion request

Warning: Permanent deletion cannot be undone and removes:

All conversation history
All configuration and settings
All metrics and analytics data
All tool associations

Best Practices

Confirm Before Deleting: Always verify the agent ID before deletion
Archive Important Data: Export conversation history if needed before deleting
Use Soft Delete: Take advantage of soft delete to avoid permanent data loss
Clean Up Resources: Consider unassigning phone numbers manually if reusing them
Monitor Impact: Check for any systems depending on the agent before deletion
Document Deletion: Keep records of why and when agents were deleted

List Agents - Get all agents (including deleted ones)
Create Agent - Create a new agent
Get Agent - Get deleted agent details
Update Agent - Reactivate a deleted agent

Delete Agent

On this page