Assign Tool to Assistant

This endpoint assigns a tool to one or more assistants, making it available during their conversations. Tools can be assigned to multiple assistants simultaneously.

Path Parameters

tool_id (integer, required): The unique identifier of the tool to assign

Request Body

Request

{
  "assistant_ids": [123, 456, 789],
  "enabled": true
}

Request Fields

assistant_ids (array of integers, required): List of assistant IDs to assign the tool to
enabled (boolean, optional): Whether the tool is enabled for these assistants (default: true)

Response

A successful request returns assignment details:

Response

{
  "success": true,
  "tool_id": 123,
  "assignments": [
    {
      "assistant_id": 123,
      "assistant_name": "Customer Service Bot",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z"
    },
    {
      "assistant_id": 456,
      "assistant_name": "Sales Assistant",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z"
    },
    {
      "assistant_id": 789,
      "assistant_name": "Technical Support",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z"
    }
  ],
  "message": "Tool successfully assigned to 3 assistants"
}

Single Assistant Assignment

You can also assign a tool to a single assistant:

Single Assignment Request

{
  "assistant_ids": [123],
  "enabled": true
}

Single Assignment Response

{
  "success": true,
  "tool_id": 123,
  "assignments": [
    {
      "assistant_id": 123,
      "assistant_name": "Customer Service Bot",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z"
    }
  ],
  "message": "Tool successfully assigned to 1 assistant"
}

Error Responses

404 Not Found - Tool

{
  "detail": "Tool with ID 123 not found"
}

404 Not Found - Assistant

{
  "detail": "Assistant with ID 456 not found in your organization"
}

400 Bad Request - Already Assigned

{
  "detail": "Tool is already assigned to assistant 123"
}

400 Bad Request - Empty Assignment

{
  "detail": "assistant_ids cannot be empty"
}

Unassign Tool

To unassign a tool from assistants, use the unassign endpoint:

Unassign Tool

POST /api/v1/tools/{tool_id}/unassign

Unassign Request

{
  "assistant_ids": [123, 456]
}

List Tool Assignments

Get all current assignments for a tool:

List Assignments

GET /api/v1/tools/{tool_id}/assignments

Assignments Response

{
  "tool_id": 123,
  "tool_name": "get_customer_info",
  "assignments": [
    {
      "assistant_id": 123,
      "assistant_name": "Customer Service Bot",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z",
      "usage_count": 45,
      "last_used_at": "2024-01-15T18:15:00Z"
    },
    {
      "assistant_id": 456,
      "assistant_name": "Sales Assistant", 
      "enabled": false,
      "assigned_at": "2024-01-15T16:30:00Z",
      "usage_count": 12,
      "last_used_at": "2024-01-15T17:20:00Z"
    }
  ],
  "total_assignments": 2
}

Integration Examples

Node.js Example

const axios = require('axios');

async function assignToolToAssistants(toolId, assistantIds, enabled = true) {
  try {
    const response = await axios.post(`https://api.burki.dev/api/v1/tools/${toolId}/assign`, {
      assistant_ids: assistantIds,
      enabled: enabled
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Failed to assign tool:', error.response.data);
    throw error;
  }
}

async function unassignToolFromAssistants(toolId, assistantIds) {
  try {
    const response = await axios.post(`https://api.burki.dev/api/v1/tools/${toolId}/unassign`, {
      assistant_ids: assistantIds
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Failed to unassign tool:', error.response.data);
    throw error;
  }
}

async function getToolAssignments(toolId) {
  try {
    const response = await axios.get(`https://api.burki.dev/api/v1/tools/${toolId}/assignments`, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Failed to get assignments:', error.response.data);
    throw error;
  }
}

// Usage examples
const result = await assignToolToAssistants(123, [456, 789]);
const assignments = await getToolAssignments(123);
await unassignToolFromAssistants(123, [456]);

Python Example

import requests
from typing import List, Dict, Any

def assign_tool_to_assistants(
    tool_id: int, 
    assistant_ids: List[int], 
    enabled: bool = True
) -> Dict[str, Any]:
    """Assign a tool to multiple assistants."""
    url = f"https://api.burki.dev/api/v1/tools/{tool_id}/assign"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {
        "assistant_ids": assistant_ids,
        "enabled": enabled
    }
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Failed to assign tool: {response.json()['detail']}")

def unassign_tool_from_assistants(
    tool_id: int, 
    assistant_ids: List[int]
) -> Dict[str, Any]:
    """Unassign a tool from multiple assistants."""
    url = f"https://api.burki.dev/api/v1/tools/{tool_id}/unassign"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {"assistant_ids": assistant_ids}
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Failed to unassign tool: {response.json()['detail']}")

def get_tool_assignments(tool_id: int) -> Dict[str, Any]:
    """Get all assignments for a tool."""
    url = f"https://api.burki.dev/api/v1/tools/{tool_id}/assignments"
    headers = {"Authorization": "Bearer YOUR_API_KEY"}
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Failed to get assignments: {response.json()['detail']}")

# Usage examples
result = assign_tool_to_assistants(123, [456, 789])
assignments = get_tool_assignments(123)
unassign_result = unassign_tool_from_assistants(123, [456])

PHP Example

<?php
function assignToolToAssistants($toolId, $assistantIds, $enabled = true) {
    $url = "https://api.burki.dev/api/v1/tools/{$toolId}/assign";
    $headers = [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json'
    ];
    
    $data = [
        'assistant_ids' => $assistantIds,
        'enabled' => $enabled
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("Failed to assign tool: " . $response);
    }
}

function getToolAssignments($toolId) {
    $url = "https://api.burki.dev/api/v1/tools/{$toolId}/assignments";
    $headers = ['Authorization: Bearer YOUR_API_KEY'];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("Failed to get assignments: " . $response);
    }
}

// Usage
$result = assignToolToAssistants(123, [456, 789]);
$assignments = getToolAssignments(123);
?>

Best Practices

Selective Assignment: Only assign tools to assistants that actually need them
Testing: Test tool functionality with specific assistants before broad deployment
Monitoring: Track tool usage per assistant to optimize assignments
Documentation: Document which tools are assigned to which assistants
Performance: Consider the number of tools per assistant for optimal performance

Use Cases

Department-Specific Tools

Scenario: Different tools for different departments

// Assign CRM lookup to sales assistants
await assignToolToAssistants(
  crmToolId, 
  [salesBot1, salesBot2, salesBot3]
);

// Assign technical diagnostics to support assistants  
await assignToolToAssistants(
  diagToolId,
  [supportBot1, supportBot2]
);

Gradual Rollout

Scenario: Rolling out new tools gradually

// Phase 1: Assign to test assistant
await assignToolToAssistants(newToolId, [testAssistant]);

// Phase 2: Assign to pilot group
await assignToolToAssistants(newToolId, [pilot1, pilot2]);

// Phase 3: Full rollout
await assignToolToAssistants(newToolId, allAssistantIds);

Temporary Access

Scenario: Temporary tool access for specific periods

// Assign tool for promotion period
await assignToolToAssistants(promoToolId, marketingBots, true);

// Later: Disable tool after promotion
await assignToolToAssistants(promoToolId, marketingBots, false);

API Documentation

Assistants

Assistant Phone Numbers

Assistant Documents (RAG)

Voice Cloning

Calls

Messaging

SIP Trunks

Billing

Phone Number Management

Call Data

Organization

Webhooks & System

Campaigns

WebSockets

Tools & Custom Actions

Conversation Flows

Learning & Memory

Path Parameters

Request Body

Request Fields

Response

Single Assistant Assignment

Error Responses

Unassign Tool

List Tool Assignments

Integration Examples

Best Practices

Use Cases

​Path Parameters

​Request Body

​Request Fields

​Response

​Single Assistant Assignment

​Error Responses

​Unassign Tool

​List Tool Assignments

​Integration Examples

​Best Practices

​Use Cases

Path Parameters

Request Body

Request Fields

Response

Single Assistant Assignment

Error Responses

Unassign Tool

List Tool Assignments

Integration Examples

Best Practices

Use Cases