Update Agent

PATCH /api/v1/agents/{agentId}

Update an existing agent's configuration, including name, status, model, instructions, config, and tools.

Endpoint

PATCH 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 update

Request Body

All fields are optional. Only include the fields you want to update.

Field	Type	Description
`name`	string	Agent name (max 255 characters)
`status`	string	Agent status: `active`, `inactive`, `training`, `deployed`
`model`	string	OpenAI model identifier
`instructions`	string	Agent behavior instructions (system prompt)
`config`	object	Type-specific configuration (voice or widget settings)
`toolIds`	array	Array of tool IDs - replaces all existing tools

Important Notes on toolIds

Providing toolIds replaces all existing tools with the new set
To remove all tools, pass an empty array: "toolIds": []
To keep existing tools unchanged, omit the toolIds field entirely
Invalid tool IDs are silently ignored

Response

Returns a confirmation with the updated agent ID.

Success Response (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "updated": true
  },
  "message": "Agent updated 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

# Update agent name and status
curl -X PATCH "https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Customer Support Agent",
    "status": "active"
  }'

# Update voice agent configuration
curl -X PATCH "https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "voice": "ballad",
      "speed": 1.2,
      "interruptionThreshold": 0.7
    }
  }'

# Update chat agent widget settings
curl -X PATCH "https://v2.heppu.ai/api/v1/agents/660e8400-e29b-41d4-a716-446655440001" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "theme": "light",
      "primaryColor": "#10B981",
      "greeting": "Hi there! Need help?"
    }
  }'

# Update agent tools (replaces all existing tools)
curl -X PATCH "https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolIds": ["web_search", "calculator", "weather"]
  }'

# Update instructions only
curl -X PATCH "https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a helpful customer support agent. Be concise and friendly."
  }'

JavaScript

// Update agent name and status
const updateAgent = async (agentId, updates) => {
  const response = await fetch(
    `https://v2.heppu.ai/api/v1/agents/${agentId}`,
    {
      method: 'PATCH',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );

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

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

// Usage examples
await updateAgent('550e8400-e29b-41d4-a716-446655440000', {
  name: 'Updated Agent Name',
  status: 'active'
});

// Update voice settings
await updateAgent('550e8400-e29b-41d4-a716-446655440000', {
  config: {
    voice: 'coral',
    speed: 1.1,
    interruptionThreshold: 0.6
  }
});

// Update tools
await updateAgent('550e8400-e29b-41d4-a716-446655440000', {
  toolIds: ['web_search', 'calendar']
});

// Deactivate agent
await updateAgent('550e8400-e29b-41d4-a716-446655440000', {
  status: 'inactive'
});

Python

import requests
import json

def update_agent(agent_id, updates):
    response = requests.patch(
        f'https://v2.heppu.ai/api/v1/agents/{agent_id}',
        headers={
            'x-api-key': 'YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json=updates
    )

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

    return response.json()['data']

# Usage examples
agent_id = '550e8400-e29b-41d4-a716-446655440000'

# Update name and status
update_agent(agent_id, {
    'name': 'Updated Customer Support Agent',
    'status': 'active'
})

# Update voice configuration
update_agent(agent_id, {
    'config': {
        'voice': 'sage',
        'speed': 1.0,
        'interruptionThreshold': 0.5
    }
})

# Update instructions
update_agent(agent_id, {
    'instructions': 'You are a helpful assistant. Be concise and clear.'
})

# Update tools (replace all)
update_agent(agent_id, {
    'toolIds': ['web_search', 'calculator', 'weather']
})

# Remove all tools
update_agent(agent_id, {
    'toolIds': []
})

Node.js (with TypeScript)

interface UpdateAgentRequest {
  name?: string;
  status?: 'active' | 'inactive' | 'training' | 'deployed';
  model?: string;
  instructions?: string;
  config?: Record<string, any>;
  toolIds?: string[];
}

interface UpdateAgentResponse {
  id: string;
  updated: boolean;
}

async function updateAgent(
  agentId: string,
  updates: UpdateAgentRequest
): Promise<UpdateAgentResponse> {
  const response = await fetch(
    `https://v2.heppu.ai/api/v1/agents/${agentId}`,
    {
      method: 'PATCH',
      headers: {
        'x-api-key': process.env.HEPPU_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(updates),
    }
  );

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

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

// Usage - Update multiple fields
await updateAgent('550e8400-e29b-41d4-a716-446655440000', {
  name: 'Updated Agent Name',
  status: 'active',
  instructions: 'New instructions here...',
});

// Usage - Update voice configuration
await updateAgent('550e8400-e29b-41d4-a716-446655440000', {
  config: {
    voice: 'ballad',
    speed: 1.2,
    interruptionThreshold: 0.7,
    timeout: 60,
  },
});

// Usage - Update chat widget
await updateAgent('660e8400-e29b-41d4-a716-446655440001', {
  config: {
    theme: 'dark',
    primaryColor: '#3B82F6',
    position: 'bottom-left',
    greeting: 'Hello! How can I assist you?',
  },
});

// Usage - Replace tools
await updateAgent('550e8400-e29b-41d4-a716-446655440000', {
  toolIds: ['web_search', 'calculator', 'weather'],
});

Common Update Patterns

Change Agent Status

// Activate agent
await updateAgent(agentId, { status: 'active' });

// Deactivate agent
await updateAgent(agentId, { status: 'inactive' });

// Mark as deployed
await updateAgent(agentId, { status: 'deployed' });

Update Voice Settings

await updateAgent(agentId, {
  config: {
    voice: 'ballad',        // Change voice
    speed: 1.2,             // Increase speed
    interruptionThreshold: 0.7  // Make more interruptible
  }
});

await updateAgent(agentId, {
  config: {
    theme: 'light',
    primaryColor: '#10B981',
    position: 'bottom-left',
    greeting: 'Hi! How can I help?'
  }
});

Add Security Restrictions (Chat Agent)

await updateAgent(agentId, {
  config: {
    allowedDomains: ['example.com', 'www.example.com', 'app.example.com']
  }
});

Change AI Model

// Switch chat agent to faster model
await updateAgent(agentId, {
  model: 'gpt-4o-mini'
});

// Switch to more capable model
await updateAgent(agentId, {
  model: 'gpt-4o'
});

Update Instructions

await updateAgent(agentId, {
  instructions: `You are a customer support agent for TechCorp.

Key responsibilities:
- Answer product questions
- Help troubleshoot issues
- Escalate to human when needed

Always be polite and professional.`
});

Add Tools

// Replace all tools with new set
await updateAgent(agentId, {
  toolIds: ['web_search', 'calculator', 'weather', 'calendar']
});

Remove All Tools

await updateAgent(agentId, {
  toolIds: []
});

Partial Updates

The PATCH method allows partial updates. Only fields included in the request body will be updated. For example:

// Only update the name - all other fields remain unchanged
await updateAgent(agentId, {
  name: 'New Agent Name'
});

// Only update specific config fields
// Note: config is replaced entirely, not merged
await updateAgent(agentId, {
  config: {
    voice: 'sage'  // This replaces the entire config object
  }
});

Config Object Behavior

Important: When updating config, the entire config object is replaced, not merged.

// Original config
{
  voice: 'sage',
  speed: 1.0,
  interruptionThreshold: 0.5,
  timeout: 30
}

// Update request
await updateAgent(agentId, {
  config: {
    voice: 'ballad'
  }
});

// Result: Only voice remains, other fields are lost
{
  voice: 'ballad'
}

// To preserve other fields, include them in the update
await updateAgent(agentId, {
  config: {
    voice: 'ballad',
    speed: 1.0,
    interruptionThreshold: 0.5,
    timeout: 30
  }
});

Best Practice: Get Before Update

To preserve existing configuration when updating, fetch the agent first:

async function safeUpdateAgent(agentId, updates) {
  // Get current agent state
  const agent = await getAgent(agentId);

  // Merge config if updating config
  if (updates.config) {
    updates.config = {
      ...agent.config,
      ...updates.config
    };
  }

  // Perform update
  return await updateAgent(agentId, updates);
}

// Usage - only voice changes, other config preserved
await safeUpdateAgent(agentId, {
  config: { voice: 'ballad' }
});

Notes

All fields are optional - only include fields you want to update
Agent must belong to your organization
Updates are immediate and affect ongoing conversations
The updatedAt timestamp is automatically set
Empty strings are valid values for name and instructions
Setting status to inactive disables the agent but preserves data
Changing the model may affect pricing and capabilities
Tool updates are atomic - the entire tool list is replaced
Configuration changes apply to new conversations immediately
Voice changes (for voice agents) take effect on the next call

List Agents - Get all agents
Create Agent - Create a new agent
Get Agent - Get detailed agent information
Delete Agent - Delete an agent